Azure API Management örneğiniz için özel etki alanı adı yapılandırma

UYGULANANLAR: Tüm API Management katmanları

Azure bulutunda bir Azure API Management hizmet örneği oluşturduğunuzda, Azure ona bir azure-api.net alt etki alanı (örneğin, apim-service-name.azure-api.net) atar. API Management uç noktalarınızı, gibi contoso.comkendi özel etki alanı adınızı kullanarak da kullanıma sağlayabilirsiniz. Bu makalede, var olan bir özel DNS adını BIR API Management örneği tarafından kullanıma sunulan uç noktalarla eşleme adımları gösterilmektedir.

Important

API Management yalnızca konak üst bilgisi değerleri eşleşen istekleri kabul eder:

• Ağ Geçidi'nin varsayılan etki alanı adı
• Ağ Geçidi'nin yapılandırılmış özel etki alanı adlarından herhangi biri

Note

Şu anda çalışma alanı ağ geçidinde özel etki alanı adları desteklenmez.

Important

API Management hizmetinizin altyapısındaki değişikliklerin (özel etki alanlarını yapılandırma, CA sertifikaları ekleme, ölçeklendirme, sanal ağ yapılandırması, kullanılabilirlik alanı değişiklikleri ve bölge eklemeleri gibi) tamamlanması, hizmet katmanına ve dağıtımın boyutuna bağlı olarak 15 dakika veya daha uzun sürebilir. Daha fazla ölçek birimi veya çok bölgeli yapılandırmaya sahip bir örnek için daha uzun süreler bekleyin. API Management'ta sıralı değişiklikler, kapasiteyi ve kullanılabilirliği korumak için dikkatle yürütülür.

Hizmet güncelleştirilirken diğer hizmet altyapısı değişiklikleri yapılamaz. Ancak API'leri, ürünleri, ilkeleri ve kullanıcı ayarlarını yapılandırabilirsiniz. Hizmet ağ geçidi kapalı kalma süresiyle karşılaşmaz ve API Management, API isteklerine kesintisiz olarak hizmet etmeye devam eder (Geliştirici katmanı hariç).

Prerequisites

• Api Management örneği. Daha fazla bilgi için bkz. Azure API Management örneği oluşturma.

• Size veya kuruluşunuza ait özel bir etki alanı adı. Bu makalede, özel bir etki alanı adı temin etme yönergeleri sağlanmaz.

• İsteğe bağlı olarak, ortak ve özel anahtara (. PFX). Konu veya konu alternatif adının (SAN) etki alanı adıyla eşleşmesi gerekir (bu, API Management örneğinin TLS üzerinden URL'leri güvenli bir şekilde kullanıma sunmasını sağlar).

  Bkz. Etki alanı sertifikası seçenekleri.

• Özel etki alanı adını API Management örneğinizin varsayılan etki alanı adıyla eşlemek için bir DNS sunucusunda barındırılan DNS kayıtları. Bu konu, DNS kayıtlarını barındırma yönergeleri sağlamaz.

  Gerekli kayıtlar hakkında daha fazla bilgi için bu makalenin devamında yer alan DNS yapılandırması bölümüne bakın.

Özel etki alanları için uç noktalar

Özel bir etki alanı adı atayabileceğiniz birkaç API Management uç noktası vardır. Şu anda aşağıdaki uç noktalar kullanılabilir:

Endpoint	Default
Gateway	Varsayılan değer: <apim-service-name>.azure-api.net. Ağ geçidi, Tüketim katmanında yapılandırma için kullanılabilen tek uç noktadır. Özel bir Ağ Geçidi etki alanı eklendikten sonra varsayılan Ağ Geçidi uç noktası yapılandırması kullanılabilir durumda kalır.
Geliştirici portalı (Tüketim dışındaki tüm katmanlar)	Varsayılan değer: <apim-service-name>.developer.azure-api.net
Yönetim (yalnızca klasik katmanlar)	Varsayılan değer: <apim-service-name>.management.azure-api.net
Kendi kendine barındırılan ağ geçidi yapılandırma API'si (v2)	Varsayılan değer: <apim-service-name>.configuration.azure-api.net
SCM (yalnızca klasik katmanlar)	Varsayılan değer: <apim-service-name>.scm.azure-api.net

Considerations

• Hizmet katmanınızda desteklenen uç noktalardan herhangi birini güncelleştirebilirsiniz. Müşteriler genellikle Ağ Geçidi'ni (bu URL API Management aracılığıyla kullanıma sunulan API'leri çağırmak için kullanılır) ve Geliştirici portalını (geliştirici portalı URL'si) güncelleştirir.
• Özel bir Ağ Geçidi etki alanı adı yapılandırdıktan sonra varsayılan Ağ Geçidi uç noktası kullanılabilir durumda kalır ve silinemez. Özel etki alanı adıyla yapılandırdığınız diğer API Management uç noktaları ( Geliştirici portalı gibi) için varsayılan uç nokta artık kullanılamaz.
• Yalnızca API Management örneği sahipleri Yönetim ve SCM uç noktalarını dahili olarak kullanabilir. Bu uç noktalara daha az sıklıkta bir özel etki alanı adı atanır.
• Premium ve Geliştirici katmanları, Ağ Geçidi uç noktası için birden çok ana bilgisayar adı ayarlamayı destekler.
• gibi *.contoso.comjoker karakter etki alanı adları, Tüketim katmanı dışındaki tüm katmanlarda desteklenir. Belirli bir alt etki alanı sertifikası (örneğin, api.contoso.com) api.contoso.com istekleri için joker sertifikadan (*.contoso.com) önceliklidir.
• Geliştirici portalı için özel bir etki alanı yapılandırırken, yeni etki alanı adı için CORS'yi etkinleştirebilirsiniz. Bu, geliştirici portalı ziyaretçilerinin API başvuru sayfalarında etkileşimli konsolu kullanabilmesi için gereklidir.

Etki alanı sertifikası seçenekleri

API Management, Azure Key Vault'tan içeri aktarılan özel TLS sertifikalarını veya sertifikaları destekler. Ücretsiz, yönetilen bir sertifikayı da etkinleştirebilirsiniz.

Warning

Sertifika sabitlemeye ihtiyacınız varsa, lütfen varsayılan sertifikayı veya ücretsiz, yönetilen sertifikayı değil, özel bir etki alanı adını ve özel veya Key Vault sertifikasını kullanın. Yönetmediğiniz bir sertifikaya sabit bağımlılık almanızı önermeyiz.

Custom

Üçüncü taraf sağlayıcıdan özel bir sertifikanız zaten varsa, bunu API Management örneğine yükleyebilirsiniz. Aşağıdaki gereksinimleri karşılaması gerekir. (API Management tarafından yönetilen ücretsiz sertifikayı etkinleştirirseniz, bu gereksinimleri zaten karşılar.)

• PFX dosyası olarak dışarı aktarılır, üçlü DES kullanılarak şifrelenir ve isteğe bağlı olarak parola korumalıdır.
• En az 2048 bit uzunluğunda özel anahtar içerir
• Sertifika zincirindeki tüm ara sertifikaları ve kök sertifikayı içerir.

Key Vault

Sertifikalarınızı yönetmek ve olarak autorenewayarlamak için Azure Key Vault kullanmanızı öneririz.

Özel etki alanı TLS sertifikasını yönetmek için Azure Key Vault kullanıyorsanız, sertifikanın Key Vault'a sertifika olarak, bir gizli değil, eklendiğinden emin olun.

Caution

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

BIR TLS/SSL sertifikası getirmek için API Management'ın listeye sahip olması ve sertifikayı içeren Azure Key Vault'ta gizli dizi izinleri alması gerekir.

• Sertifikayı içeri aktarmak için Azure portalını kullandığınızda, gerekli tüm yapılandırma adımları otomatik olarak tamamlanır.

• Komut satırı araçlarını veya yönetim API'sini kullandığınızda, bu izinler iki adımda el ile verilmelidir:

  1. API Management örneğinizin Yönetilen kimlikler sayfasında sistem tarafından atanan veya kullanıcı tarafından atanan yönetilen kimliği etkinleştirin. Bu sayfadaki asıl kimliği not edin.
  2. Anahtar kasasına erişmek için yönetilen kimliğe izinler atayın. Aşağıdaki bölümdeki adımları kullanın.

  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 Yönetimi yönetilen kimliği için bir anahtar kasası erişim ilkesi veya 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, 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 kimlikleri seçin penceresinde, SISTEM tarafından atanan yönetilen kimliği veya API Management örneğiniz ile ilişkili kullanıcı tarafından atanan yönetilen kimliği seçin ve ardından Seç'e tıklayın.
  6. Gözden geçir ve ata seçin.

Sertifika olarak autorenew ayarlandıysa ve API Management katmanınızın bir SLA'sı varsa (Geliştirici katmanı dışındaki tüm katmanlarda), API Management hizmette kapalı kalma süresi olmadan en son sürümü otomatik olarak alır.

Daha fazla bilgi için bkz. Azure API Management'ta yönetilen kimlikleri kullanma.

Managed

Kendi sertifikanızı satın almak ve yönetmek istemiyorsanız API Management, etki alanınız için ücretsiz, yönetilen bir TLS sertifikası sunar. Sertifika otomatik olarak yeniden oluşturulur.

Important

API Management'ta özel etki alanları için yönetilen sertifikaların oluşturulması 15 Ağustos 2025 ile 15 Mart 2026 tarihleri arası geçici olarak kullanılamayacaktır. Sertifika Yetkilimiz (CA), DigiCert, sertifika verme için Çok Perspektifli Verme Doğrulama (MPIC) gereksinimlerini karşılamak üzere yeni bir doğrulama platformuna geçiş yapacaktır. Bu geçiş, özel etki alanları için yönetilen sertifikaların oluşturulmasını geçici olarak askıya almamızı gerektirir. Daha fazla bilgi edinin

Mevcut yönetilen sertifikalar otomatik olarak yenilenir ve etkilenmez.

Yönetilen sertifikaların oluşturulması askıya alınırken, özel etki alanlarını yapılandırmak için diğer sertifika seçeneklerini kullanın.

Note

Ücretsiz, yönetilen TLS sertifikası önizleme aşamasındadır.

Limitations

• Şu anda yalnızca API Management hizmetinizin Ağ Geçidi uç noktasıyla kullanılabilir
• v2 katmanlarında desteklenmez
• Şirket içinde barındırılan ağ geçidiyle desteklenmez
• Şu Azure bölgelerinde desteklenmez: Fransa Güney ve Güney Afrika Batı
• Şu anda yalnızca Azure bulutunda kullanılabilir
• Kök etki alanı adlarını (örneğin, contoso.com) desteklemez. gibi api.contoso.comtam bir ad gerektirir.
• Yalnızca ortak etki alanı adlarını destekler
• Yalnızca mevcut bir API Management örneği güncelleştirilirken yapılandırılabilir, örnek oluşturulurken yapılandırılamaz

Özel etki alanı adı ayarlama - portal

Kullanmak istediğiniz etki alanı sertifikasına göre adımları seçin.

Custom

1. Azure portalında API Management örneğine gidin.
2. Sol gezinti bölmesinde Özel etki alanları'nı seçin.
3. +Ekle'yi seçin veya güncelleştirmek istediğiniz mevcut bir uç noktayı seçin.
4. Sağdaki pencerede özel etki alanı için uç nokta türü'nü seçin.
5. Konak adı alanında, kullanmak istediğiniz adı belirtin. Örneğin, api.contoso.com.
6. Sertifika'nın altında Özel'i seçin
7. Sertifikayı seçmek ve karşıya yüklemek için Sertifika dosyası'na tıklayın.
8. Geçerli bir .PFX dosyasını karşıya yükleyin ve sertifika bir parolayla korunuyorsa Parolasını sağlayın.
9. Ağ geçidi uç noktasını yapılandırırken, gerektiğinde İstemci sertifikasını müzakere et veya Varsayılan SSL bağlaması gibi diğer seçenekleri seçin veya seçimini kaldırın.
10. Ekle'yi seçin veya mevcut bir uç nokta için Güncelleştir'i seçin.
11. Kaydetseçeneğini seçin.

Key Vault

1. Azure portalında API Management örneğine gidin.
2. Sol gezinti bölmesinde Özel etki alanları'nı seçin.
3. +Ekle'yi seçin veya güncelleştirmek istediğiniz mevcut bir uç noktayı seçin.
4. Sağdaki pencerede özel etki alanı için uç nokta türü'nü seçin.
5. Konak adı alanında, kullanmak istediğiniz adı belirtin. Örneğin, api.contoso.com.
6. Sertifika'nın altında Key Vault'a ve ardından Seç'e tıklayın.
   1. Açılan listeden Abonelik'i seçin.
   2. Açılan listeden anahtar kasası seçin.
   3. Sertifikalar yüklendikten sonra açılan listeden Sertifika'yı seçin. Seç'e tıklayın.
   4. İstemci Kimliği bölümünde, anahtar kasasına erişim sağlamak için örnekte etkinleştirilen sistem tarafından atanan bir kimlik veya kullanıcı tarafından atanan yönetilen kimliği seçin.
7. Ağ geçidi uç noktasını yapılandırırken, gerektiğinde İstemci sertifikasını müzakere et veya Varsayılan SSL bağlaması gibi diğer seçenekleri seçin veya seçimini kaldırın.
8. Ekle'yi seçin veya mevcut bir uç nokta için Güncelleştir'i seçin.
9. Kaydetseçeneğini seçin.

Managed

1. Azure portalında API Management örneğine gidin.
2. Sol gezinti bölmesinde Özel etki alanları'nı seçin.
3. +Ekle'yi seçin veya güncelleştirmek istediğiniz mevcut bir uç noktayı seçin.
4. Sağdaki pencerede özel etki alanı için uç nokta türü'nü seçin.
5. Konak adı alanında, kullanmak istediğiniz adı belirtin. Örneğin, api.contoso.com.
6. API Management tarafından yönetilen ücretsiz bir sertifikayı etkinleştirmek için Sertifika'nın altında Yönetilen'i seçin. Yönetilen sertifika yalnızca Ağ Geçidi uç noktası için önizlemede kullanılabilir.
7. Aşağıdaki değerleri kopyalayın ve DNS'yi yapılandırmak için kullanın:
   • TXT kaydı
   • CNAME kaydı
8. Ağ geçidi uç noktasını yapılandırırken, gerektiğinde İstemci sertifikasını müzakere et veya Varsayılan SSL bağlaması gibi diğer seçenekleri seçin veya seçimini kaldırın.
9. Ekle'yi seçin veya mevcut bir uç nokta için Güncelleştir'i seçin.
10. Kaydetseçeneğini seçin.

DNS yapılandırması

• Özel etki alanınız için bir CNAME kaydı yapılandırın.
• API Management'ın ücretsiz, yönetilen sertifikasını kullanırken, etki alanının sahipliğini oluşturmak için bir TXT kaydı da yapılandırın.

Note

Ücretsiz sertifika DigiCert tarafından verilir. Bazı etki alanları için, şu değere sahip bir CAA etki alanı kaydı oluşturarak

CNAME record

Özel etki alanı adınızdan (örneğin, api.contoso.com) API Management hizmeti ana bilgisayar adınıza (örneğin, <apim-service-name>.azure-api.net) işaret eden bir CNAME kaydı yapılandırın. CNAME kaydı, IP adresinin değişmesi durumunda A kaydından daha kararlıdır. Daha fazla bilgi için Azure API Yönetiminin IP adresleri ve API Yönetimi SSS'ye bakın.

Note

Bazı etki alanı kayıt şirketleri, gibi www.contoso.comkök adları değil, gibi contoso.combir CNAME kaydı kullanırken alt etki alanları eşlemenize izin verir. CNAME kayıtları hakkında daha fazla bilgi için kayıt şirketiniz veya IETF Etki Alanı Adları - Uygulama ve Belirtim tarafından sağlanan belgelere bakın.

Caution

Ücretsiz, yönetilen sertifikayı kullandığınızda ve DNS sağlayıcınızla bir CNAME kaydı yapılandırdığınızda, bunun varsayılan API Management hizmeti ana bilgisayar adına (<apim-service-name>.azure-api.net ) çözümlendiğinden emin olun. Şu anda, CNAME kaydı varsayılan API Management ana bilgisayar adına çözümlenmezse API Management sertifikayı otomatik olarak yenilemez. Örneğin, ücretsiz, yönetilen sertifikayı kullanıyorsanız ve DNS sağlayıcınız olarak Cloudflare kullanıyorsanız, CNAME kaydında DNS proxy'sinin etkinleştirilmediğinden emin olun.

TXT record

API Management için ücretsiz, yönetilen sertifikayı etkinleştirirken, etki alanı adının sahipliğini oluşturmak için DNS bölgenizde bir TXT kaydı da yapılandırın.

• Kaydın adı, ön ekinde apimuidbulunan özel etki alanı adınızdır. Örnek: apimuid.api.contoso.com.
• Değer, API Management örneğiniz tarafından sağlanan bir etki alanı sahipliği tanımlayıcısıdır.

Portalı kullanarak özel etki alanınız için ücretsiz, yönetilen sertifikayı yapılandırdığınızda, gerekli TXT kaydının adı ve değeri otomatik olarak görüntülenir.

Etki Alanı Sahipliği Tanımlayıcısı Al REST API'sini çağırarak da bir etki alanı sahipliği tanımlayıcısı alabilirsiniz.

API Management proxy sunucusu TLS el sıkışmasında SSL sertifikaları ile nasıl yanıt verir?

Ağ Geçidi uç noktası için özel bir etki alanı yapılandırırken, istemci isteğine bağlı olarak API Management'ın sunucu sertifikasıyla nasıl yanıt vereceğini belirleyen ek özellikler ayarlayabilirsiniz.

Sunucu Adı Göstergesi (SNI) üst bilgisi ile çağıran istemciler

Ağ Geçidi uç noktası için yapılandırılmış bir veya birden çok özel etki alanınız varsa, API Management https isteklerine aşağıdakilerden birinden yanıt verebilir:

• Özel etki alanı (örneğin, contoso.com)
• Varsayılan etki alanı (örneğin, apim-service-name.azure-api.net).

API Management, SNI üst bilgisindeki bilgilere bağlı olarak uygun sunucu sertifikasıyla yanıt verir.

SNI üst bilgisi olmadan çağrı yapan istemciler

SNI üst bilgisini göndermeyen bir istemci kullanıyorsanız, API Management aşağıdaki mantığı temel alarak yanıtlar oluşturur:

• Hizmette Ağ Geçidi için yapılandırılmış yalnızca bir özel etki alanı varsa, varsayılan sertifika Ağ Geçidi'nin özel etki alanına verilen sertifikadır.

• Hizmet Ağ Geçidi için birden çok özel etki alanı yapılandırdıysa ( Geliştirici ve Premium katmanında desteklenir)defaultSslBinding özelliğini true ("defaultSslBinding":"true" olarak ayarlayarak varsayılan sertifikayı belirleyebilirsiniz. Portalda Varsayılan SSL bağlama onay kutusunu seçin.

  Özelliğini ayarlamazsanız, varsayılan sertifika konumunda *.azure-api.netbarındırılan varsayılan Ağ Geçidi etki alanına verilen sertifikadır.

Büyük yüke sahip PUT/POST isteği desteği

API Management proxy sunucusu, HTTPS'de istemci tarafı sertifikaları kullanılırken büyük yükleri (>40 KB) olan istekleri destekler. Sunucunun isteğinin donmasını önlemek için negotiateClientCertificate özelliğini Ağ Geçidi ana bilgisayar adında true ("negotiateClientCertificate": "true") olarak ayarlayabilirsiniz. Portalda İstemci sertifikası anlaşması onay kutusunu seçin.

Özellik true olarak ayarlanırsa, istemci sertifikası herhangi bir HTTP isteği değişiminden önce SSL/TLS bağlantı zamanında istenir. Ayar Ağ Geçidi ana bilgisayar adı düzeyinde uygulandığından, tüm bağlantı istekleri istemci sertifikasını ister. Bu sınırlamayı aşabilir ve Ağ Geçidi için en fazla 20 adet özel alan adı yapılandırabilirsiniz (yalnızca Premium katmanında desteklenir).

v2 katmanlarında özel etki alanı adı kısıtlaması

Şu anda Standart v2 ve Premium v2 katmanlarında API Management, Ağ Geçidi uç noktasına giden trafiğe izin vermek için genel olarak çözümlenebilir bir DNS adı gerektirir. Ağ Geçidi uç noktası için bir özel etki alanı adı yapılandırdığınızda, bu ad, Özel DNS bölgesiyle sınırlı olmamalı ve genel olarak çözümlenebilir olmalıdır.

Ağ geçidine genel erişimi sınırladığınız ve özel bir etki alanı adı yapılandırdığınız senaryolarda geçici bir çözüm olarak Application Gateway'i özel etki alanı adında trafik alacak şekilde ayarlayabilir ve API Management örneğinin Ağ Geçidi uç noktasına yönlendirebilirsiniz. Örnek bir mimari için bu GitHub deposuna bakın.

Sorun giderme: Azure Key Vault'tan ana bilgisayar adı sertifika döndürme başarısız oldu

Yapılandırma değişikliği veya bağlantı sorunu nedeniyle API Management örneğiniz, bir sertifika orada güncelleştirildikten veya döndürüldükten sonra Azure Key Vault'tan bir konak adı sertifikası getiremeyebilir. Bu durumda API Management örneğiniz, güncelleştirilmiş bir sertifikayı alana kadar önbelleğe alınmış bir sertifika kullanmaya devam eder. Önbelleğe alınan sertifikanın süresi dolarsa ağ geçidine yönelik çalışma zamanı trafiği engellenir. Ana bilgisayar adı sertifika yapılandırmasını kullanan Application Gateway gibi herhangi bir yukarı akış hizmeti, süresi dolan önbelleğe alınmış bir sertifika kullanıldığında ağ geçidine yönelik çalışma zamanı trafiğini de engelleyebilir.

Bu sorunu azaltmak için anahtar kasasının mevcut olduğunu ve sertifikanın anahtar kasasında depolandığını onaylayın. API Management örneğiniz bir sanal ağda dağıtıldıysa AzureKeyVault hizmet etiketine giden bağlantıyı onaylayın. Anahtar kasasına erişmek için kullanılan yönetilen kimliğin mevcut olup olmadığını denetleyin. Yönetilen kimliğin anahtar kasasına erişim izinlerini onaylayın. Ayrıntılı yapılandırma adımları için bu makalenin önceki bölümlerinde yer alan Özel etki alanı adı ayarlama - Key Vault makalesini gözden geçirin. Yapılandırma geri yüklendikten sonra konak adı sertifikası API Management'ta 4 saat içinde yenilenir.

İlgili içerik

Hizmetinizi yükseltme ve ölçeklendirme