Skonfiguruj niestandardową nazwę domeny dla swojej instancji usługi Azure API Management

DOTYCZY: Wszystkie warstwy usługi API Management

Podczas tworzenia wystąpienia usługi Azure API Management w chmurze platformy Azure platforma Azure przypisuje jej poddomenę azure-api.net (na przykład apim-service-name.azure-api.net). Punkty końcowe usługi API Management można również uwidocznić przy użyciu własnej niestandardowej nazwy domeny, takiej jak contoso.com. W tym artykule pokazano, jak zamapować istniejącą niestandardową nazwę DNS na punkty końcowe uwidocznione przez wystąpienie usługi API Management.

Important

Usługa API Management akceptuje tylko żądania z zgodnymi wartościami nagłówka hosta :

• Domyślna nazwa domeny bramki
• Dowolna ze skonfigurowanych niestandardowych nazw domen bramy

Note

Obecnie niestandardowe nazwy domen nie są obsługiwane w bramie obszaru roboczego.

Important

Zmiany w infrastrukturze usługi API Management (takie jak konfigurowanie domen niestandardowych, dodawanie certyfikatów urzędu certyfikacji, skalowanie, konfiguracja sieci wirtualnej, zmiany strefy dostępności i dodawanie regionów) mogą potrwać 15 minut lub dłużej, w zależności od warstwy usługi i rozmiaru wdrożenia. Spodziewaj się dłuższego czasu działania instancji z większą liczbą jednostek skalowania lub z konfiguracją obejmującą wiele regionów. Zmiany etapowe w usłudze API Management są wykonywane ostrożnie, aby zachować pojemność i dostępność.

Podczas aktualizowania usługi nie można wprowadzać innych zmian infrastruktury usług. Można jednak skonfigurować interfejsy API, produkty, zasady i ustawienia użytkownika. Usługa nie doświadczy przestoju bramy, a zarządzanie interfejsem API będzie nadal obsługiwać żądania bez przerwy (z wyjątkiem poziomu Deweloper).

Prerequisites

• Instancja zarządzania API. Aby uzyskać więcej informacji, zobacz Tworzenie wystąpienia usługi Azure API Management.

• Niestandardowa nazwa domeny, która jest własnością Ciebie lub Twojej organizacji. Ten artykuł nie zawiera instrukcji dotyczących uzyskiwania niestandardowej nazwy domeny.

• Opcjonalnie prawidłowy certyfikat z kluczem publicznym i prywatnym (. PFX). Nazwa podmiotu lub alternatywna nazwa podmiotu (SAN) musi być zgodna z nazwą domeny (dzięki temu wystąpienie usługi API Management może bezpiecznie udostępnić adresy URL za pośrednictwem protokołu TLS).

  Zobacz Opcje certyfikatu domeny.

• Rekordy DNS, hostowane na serwerze DNS, służą do mapowania niestandardowej nazwy domeny na domyślną nazwę domeny wystąpienia usługi API Management. Ten temat nie zawiera instrukcji dotyczących hostowania rekordów DNS.

  Aby uzyskać więcej informacji na temat wymaganych rekordów, zobacz Konfiguracja DNS w dalszej części tego artykułu.

Punkty końcowe dla domen niestandardowych

Istnieje kilka punktów końcowych usługi API Management, do których można przypisać niestandardową nazwę domeny. Obecnie dostępne są następujące punkty końcowe:

Endpoint	Default
Gateway	Wartość domyślna to: <apim-service-name>.azure-api.net. Brama jest jedynym punktem końcowym dostępnym do skonfigurowania w warstwie Zużycie. Domyślna konfiguracja punktu końcowego bramy pozostaje dostępna po dodaniu niestandardowej domeny bramy.
Portal dla deweloperów (wszystkie poziomy oprócz Konsumpcji)	Wartość domyślna to: <apim-service-name>.developer.azure-api.net
Zarządzanie (tylko warstwy klasyczne)	Wartość domyślna to: <apim-service-name>.management.azure-api.net
API konfiguracji samodzielnie hostowanej bramy sieciowej (wersja 2)	Wartość domyślna to: <apim-service-name>.configuration.azure-api.net
SCM (tylko warstwy klasyczne)	Wartość domyślna to: <apim-service-name>.scm.azure-api.net

Considerations

• Możesz zaktualizować dowolne punkty końcowe obsługiwane w warstwie usługi. Zazwyczaj klienci aktualizują bramę (ten adres URL służy do wywoływania interfejsów API udostępnianych za pośrednictwem usługi API Management) i portalu deweloperów (adresu URL portalu deweloperów).
• Domyślny punkt końcowy bramy pozostaje dostępny nawet po skonfigurowaniu niestandardowej nazwy domeny dla bramy oraz nie można go usunąć. W przypadku innych punktów końcowych usługi API Management (takich jak portal dla deweloperów) skonfigurowanych przy użyciu niestandardowej nazwy domeny domyślny punkt końcowy nie jest już dostępny.
• Tylko właściciele wystąpień usługi API Management mogą używać wewnętrznie punktów końcowych Management i SCM. Tym punktom końcowym rzadziej przypisuje się niestandardową nazwę domeny.
• Poziomy Premium i Deweloper obsługują ustawianie wielu nazw domenowych dla punktu końcowego Gateway.
• Nazwy domen z symbolami wieloznacznymi, takie jak *.contoso.com, są obsługiwane we wszystkich warstwach z wyjątkiem warstwy konsumpcyjnej. Określony certyfikat poddomeny (takich jak api.contoso.com) będzie miał pierwszeństwo nad certyfikatem wieloznacznym (*.contoso.com), gdy żądania dotyczą api.contoso.com.
• Podczas konfigurowania domeny niestandardowej dla portalu deweloperów można włączyć mechanizm CORS dla nowej nazwy domeny. Jest to wymagane, aby odwiedzający portal dla deweloperów używali interaktywnej konsoli na stronach referencyjnych interfejsu API.

Opcje certyfikatu domeny

Usługa API Management obsługuje niestandardowe certyfikaty protokołu TLS lub certyfikaty importowane z usługi Azure Key Vault. Możesz również włączyć bezpłatny, zarządzany certyfikat.

Warning

Jeśli potrzebujesz przypinania certyfikatów, użyj własnej nazwy domeny i własnego certyfikatu lub certyfikatu usługi Key Vault, a nie certyfikatu domyślnego ani bezpłatnego certyfikatu zarządzanego. Nie zalecamy podejmowania twardej zależności od certyfikatu, którym nie zarządzasz.

Custom

Jeśli masz już certyfikat prywatny od dostawcy innej firmy, możesz przekazać go do wystąpienia usługi API Management. Musi spełniać następujące wymagania. (Jeśli włączysz bezpłatny certyfikat zarządzany przez usługę API Management, spełnia już te wymagania).

• Wyeksportowany jako plik PFX zaszyfrowany przy użyciu potrójnego des i opcjonalnie chroniony hasłem.
• Zawiera klucz prywatny o długości co najmniej 2048 bitów
• Zawiera wszystkie certyfikaty pośrednie i certyfikat główny w łańcuchu certyfikatów.

Key Vault

Zalecamy używanie usługi Azure Key Vault do zarządzania certyfikatami i ustawiania ich na .autorenew

Jeśli używasz usługi Azure Key Vault do zarządzania certyfikatem TLS domeny niestandardowej, upewnij się, że certyfikat został wstawiony do usługi Key Vault jako certyfikat, a nie wpis tajny.

Caution

W przypadku korzystania z certyfikatu magazynu kluczy w usłudze API Management należy zachować ostrożność, aby nie usuwać certyfikatu, magazynu kluczy lub tożsamości zarządzanej używanej do uzyskiwania dostępu do magazynu kluczy.

Aby pobrać certyfikat TLS/SSL, usługa API Management musi mieć uprawnienia do listowania i uzyskiwania tajemnic w usłudze Azure Key Vault zawierającej certyfikat.

• W przypadku importowania certyfikatu przy użyciu witryny Azure Portal wszystkie niezbędne kroki konfiguracji są wykonywane automatycznie.

• Jeśli używasz narzędzi wiersza polecenia lub interfejsu API zarządzania, te uprawnienia muszą zostać przyznane ręcznie, w dwóch krokach:

  1. Na stronie Tożsamości zarządzane wystąpienia usługi API Management włącz tożsamość zarządzaną przypisaną przez system lub przypisaną przez użytkownika. Zanotuj główny identyfikator na tej stronie.
  2. Przypisz uprawnienia dostępowe do tożsamości zarządzanej, aby uzyskać dostęp do magazynu kluczy. Wykonaj kroki opisane w poniższej sekcji.

  Konfigurowanie dostępu do magazynu kluczy

  1. W portalu przejdź do skrytki kluczy.
  2. W menu po lewej stronie wybierz pozycję Ustawienia>Konfiguracja dostępu. Zwróć uwagę na skonfigurowany model uprawnień .
  3. W zależności od modelu uprawnień skonfiguruj zasady dostępu magazynu kluczy lub dostęp RBAC platformy Azure dla tożsamości zarządzanej usługi API Management.

  Aby dodać zasady dostępu do magazynu kluczy:

  1. W menu po lewej stronie wybierz pozycję Zasady dostępu.
  2. Na stronie Zasady dostępu wybierz pozycję + Utwórz.
  3. Na karcie Uprawnienia w obszarze Uprawnienia w obszarze Uprawnienia tajne wybierz pozycję Pobierz i wyświetl, a następnie wybierz pozycję Dalej.
  4. Na karcie Główne wyszukaj nazwę zasobu tożsamości zarządzanej, a następnie wybierz pozycję Dalej. Jeśli używasz tożsamości przypisanej przez system, podmiot to nazwa wystąpienia usługi API Management.
  5. Ponownie wybierz przycisk Dalej . Na karcie Przeglądanie i tworzenie wybierz pozycję Utwórz.

  Aby skonfigurować dostęp RBAC platformy Azure:

  1. W menu po lewej stronie wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami)..
  2. Na stronie Kontrola dostępu (Zarządzanie dostępem i tożsamościami) wybierz pozycję Dodaj przypisanie roli.
  3. Na karcie Rola wybierz pozycję Użytkownik certyfikatu usługi Key Vault.
  4. Na karcie Członkowie wybierz opcję Tożsamość zarządzana>+ Wybierz członków.
  5. W oknie Wybieranie tożsamości zarządzanych wybierz tę tożsamość zarządzaną przypisaną przez system lub tożsamość zarządzaną przypisaną przez użytkownika skojarzoną z wystąpieniem usługi API Management, a następnie kliknij Wybierz.
  6. Wybierz pozycję Przejrzyj i przypisz.

Jeśli certyfikat jest ustawiony na autorenew, a warstwa usługi Zarządzanie API ma umowę SLA (czyli we wszystkich warstwach z wyjątkiem warstwy Dewelopera), usługa Zarządzanie API automatycznie pobierze najnowszą wersję bez przestoju usługi.

Aby uzyskać więcej informacji, zobacz Używanie tożsamości zarządzanych w usłudze Azure API Management.

Managed

Usługa API Management oferuje bezpłatny, zarządzany certyfikat TLS dla twojej domeny, jeśli nie chcesz kupować własnego certyfikatu i zarządzać nim. Certyfikat jest odnawiany automatycznie.

Important

Tworzenie certyfikatów zarządzanych dla domen niestandardowych w usłudze API Management będzie tymczasowo niedostępne od 15 sierpnia 2025 r. do 15 marca 2026 r. Nasz urząd certyfikacji (CA), DigiCert, przeprowadzi migrację do nowej platformy weryfikacji, aby spełnić wymagania dotyczące weryfikacji z wieloma perspektywami (MPIC) dotyczące wystawiania certyfikatów. Ta migracja wymaga tymczasowego zawieszenia tworzenia certyfikatów zarządzanych dla domen niestandardowych. Dowiedz się więcej

Istniejące certyfikaty zarządzane zostaną automatycznie odnowione i pozostaną nienaruszone.

Gdy tworzenie certyfikatów zarządzanych jest zawieszone, użyj innych opcji certyfikacji do konfigurowania domen niestandardowych.

Note

Bezpłatny zarządzany certyfikat TLS jest w wersji zapoznawczej.

Limitations

• Obecnie może być używane tylko z punktem końcowym bramy usługi zarządzania API
• Nieobsługiwane w warstwach v2
• Nieobsługiwane przez bramę własnego hostingu
• Nieobsługiwane w następujących regionach świadczenia usługi Azure: Francja Południowa i Republika Południowej Afryki Zachodnia
• Obecnie dostępne tylko w chmurze platformy Azure
• Nie obsługuje nazw domen głównych (na przykład contoso.com). Wymaga w pełni kwalifikowanej nazwy, takiej jak api.contoso.com.
• Obsługuje tylko nazwy domen publicznych
• Można skonfigurować tylko podczas aktualizowania istniejącego wystąpienia usługi API Management, a nie podczas tworzenia wystąpienia

Ustawianie niestandardowej nazwy domeny — portal

Wybierz kroki zgodnie z certyfikatem domeny , którego chcesz użyć.

Custom

1. Przejdź do wystąpienia usługi API Management w witrynie Azure Portal.
2. W obszarze nawigacji po lewej stronie wybierz pozycję Domeny niestandardowe.
3. Wybierz pozycję +Dodaj lub wybierz istniejący punkt końcowy , który chcesz zaktualizować.
4. W oknie po prawej stronie wybierz typ punktu końcowego dla domeny niestandardowej.
5. W polu Nazwa hosta określ nazwę, której chcesz użyć. Na przykład api.contoso.com.
6. W obszarze Certyfikat wybierz pozycję Niestandardowe
7. Wybierz Plik certyfikatu, aby wybrać i przesłać certyfikat.
8. Przekaż prawidłowy plik .PFX i podaj hasło, jeśli certyfikat jest chroniony hasłem.
9. Podczas konfigurowania punktu końcowego bramy, zaznacz lub odznacz inne opcje w miarę potrzeby, w tym negocjuj certyfikat klienta lub domyślne powiązanie SSL.
10. Wybierz pozycję Dodaj lub wybierz pozycję Aktualizuj dla istniejącego punktu końcowego.
11. Wybierz Zapisz.

Key Vault

1. Przejdź do wystąpienia usługi API Management w witrynie Azure Portal.
2. W obszarze nawigacji po lewej stronie wybierz pozycję Domeny niestandardowe.
3. Wybierz pozycję +Dodaj lub wybierz istniejący punkt końcowy , który chcesz zaktualizować.
4. W oknie po prawej stronie wybierz typ punktu końcowego dla domeny niestandardowej.
5. W polu Nazwa hosta określ nazwę, której chcesz użyć. Na przykład api.contoso.com.
6. W obszarze Certyfikat wybierz pozycję Key Vault, a następnie Wybierz.
   1. Wybierz pozycję Subskrypcja z listy rozwijanej.
   2. Wybierz magazyn kluczy z listy rozwijanej.
   3. Po załadowaniu certyfikatów wybierz pozycję Certyfikat z listy rozwijanej. Kliknij opcję Wybierz.
   4. W obszarze Tożsamość klienta wybierz tożsamość przypisaną przez system lub zarządzaną tożsamość przypisaną przez użytkownika, która jest włączona w wystąpieniu, aby uzyskać dostęp do magazynu kluczy.
7. Podczas konfigurowania punktu końcowego bramy, zaznacz lub odznacz inne opcje w miarę potrzeby, w tym negocjuj certyfikat klienta lub domyślne powiązanie SSL.
8. Wybierz pozycję Dodaj lub wybierz pozycję Aktualizuj dla istniejącego punktu końcowego.
9. Wybierz Zapisz.

Managed

1. Przejdź do wystąpienia usługi API Management w witrynie Azure Portal.
2. W obszarze nawigacji po lewej stronie wybierz pozycję Domeny niestandardowe.
3. Wybierz pozycję +Dodaj lub wybierz istniejący punkt końcowy , który chcesz zaktualizować.
4. W oknie po prawej stronie wybierz typ punktu końcowego dla domeny niestandardowej.
5. W polu Nazwa hosta określ nazwę, której chcesz użyć. Na przykład api.contoso.com.
6. W obszarze Certyfikat wybierz pozycję Zarządzane , aby włączyć bezpłatny certyfikat zarządzany przez usługę API Management. Certyfikat zarządzany jest dostępny tylko w wersji testowej dla punktu końcowego bramy.
7. Skopiuj następujące wartości i użyj ich do skonfigurowania systemu DNS:
   • Rekordy TXT
   • Rekord CNAME
8. Podczas konfigurowania punktu końcowego bramy, zaznacz lub odznacz inne opcje w miarę potrzeby, w tym negocjuj certyfikat klienta lub domyślne powiązanie SSL.
9. Wybierz pozycję Dodaj lub wybierz pozycję Aktualizuj dla istniejącego punktu końcowego.
10. Wybierz Zapisz.

Konfiguracja DNS

• Skonfiguruj rekord CNAME dla domeny niestandardowej.
• W przypadku korzystania z bezpłatnego certyfikatu zarządzanego usługi API Management skonfiguruj również rekord TXT w celu ustanowienia własności domeny.

Note

Bezpłatny certyfikat jest wystawiany przez firmę DigiCert. W przypadku niektórych domen należy jawnie zezwolić firmie DigiCert na wystawcę certyfikatów, tworząc rekord domeny CAA z wartością : 0 issue digicert.com.

rekord CNAME

Skonfiguruj rekord CNAME wskazujący z nazwy domeny niestandardowej (na przykład api.contoso.com) na nazwę hosta usługi API Management (na przykład <apim-service-name>.azure-api.net). Rekord CNAME jest bardziej stabilny niż rekord A w przypadku zmiany adresu IP. Aby uzyskać więcej informacji, zobacz adresy IP usługi Azure API Management i często zadawane pytania dotyczące usługi API Management.

Note

Niektórzy rejestratorzy domen umożliwiają mapowanie domen podrzędnych tylko w przypadku używania rekordu CNAME, takiego jak , i nie nazw głównych, takich jak www.contoso.comcontoso.com. Aby uzyskać więcej informacji na temat rekordów CNAME, zobacz dokumentację dostarczoną przez rejestratora lub nazwy domen IETF — implementacja i specyfikacja.

Caution

W przypadku korzystania z bezpłatnego certyfikatu zarządzanego i konfigurowania rekordu CNAME u dostawcy DNS upewnij się, że jest rozpoznawany jako domyślna nazwa hosta usługi API Management (<apim-service-name>.azure-api.net). Obecnie usługa API Management nie odnawia automatycznie certyfikatu, jeśli rekord CNAME nie wskazuje na domyślną nazwę hosta usługi API Management. Jeśli na przykład używasz bezpłatnego, zarządzanego certyfikatu i używasz usługi Cloudflare jako dostawcy DNS, upewnij się, że serwer proxy DNS nie jest włączony w rekordzie CNAME.

rekord TXT

Po włączeniu bezpłatnego zarządzanego certyfikatu usługi API Management skonfiguruj również rekord TXT w strefie DNS, aby ustanowić własność nazwy domeny.

• Nazwa rekordu to niestandardowa nazwa domeny poprzedzona prefiksem apimuid. Przykład: apimuid.api.contoso.com.
• Wartość jest identyfikatorem własności domeny dostarczonym przez wystąpienie usługi API Management.

Gdy używasz portalu do konfigurowania bezpłatnego certyfikatu zarządzanego dla domeny niestandardowej, nazwa i wartość niezbędnego rekordu TXT są wyświetlane automatycznie.

Identyfikator własności domeny można również uzyskać, wywołując interfejs API REST Uzyskiwanie własności domeny .

Jak serwer proxy usługi API Management reaguje przy użyciu certyfikatów SSL w uzgadnianiu protokołu TLS

Podczas konfigurowania domeny niestandardowej dla punktu końcowego bramy można ustawić dodatkowe właściwości określające sposób reagowania usługi API Management przy użyciu certyfikatu serwera w zależności od żądania klienta.

Klienci dzwoniący z nagłówkiem Server Name Indication (SNI)

Jeśli masz jedną lub wiele domen niestandardowych skonfigurowanych dla punktu końcowego bramy, usługa API Management może odpowiadać na żądania HTTPS:

• Domena niestandardowa (na przykład contoso.com)
• Domena domyślna (na przykład apim-service-name.azure-api.net).

Na podstawie informacji zawartych w nagłówku SNI, usługa API Management odpowiada, dostarczając odpowiedni certyfikat serwera.

Klienci dzwoniący bez nagłówka SNI

Jeśli używasz klienta, który nie wysyła nagłówka SNI , usługa API Management tworzy odpowiedzi na podstawie następującej logiki:

• Jeśli usługa ma tylko jedną domenę niestandardową skonfigurowaną dla bramy, domyślnym certyfikatem jest certyfikat wystawiony dla domeny niestandardowej bramy.

• Jeśli usługa skonfigurowała wiele domen niestandardowych dla Gateway (obsługiwanej w warstwie Deweloper i Premium), można ustawić certyfikat domyślny, ustawiając właściwość defaultSslBinding na true ("defaultSslBinding":"true"). W portalu zaznacz pole wyboru Domyślne powiązanie SSL .

  Jeśli właściwość nie zostanie ustawiona, domyślnym certyfikatem jest certyfikat wystawiony dla domyślnej domeny bramy hostowanej pod adresem *.azure-api.net.

Obsługa żądania PUT/POST z dużym ładunkiem

Serwer proxy usługi API Management obsługuje żądania z dużymi ładunkami (>40 KB) w przypadku używania certyfikatów po stronie klienta w protokole HTTPS. Aby zapobiec zamrożeniu żądania serwera, możesz ustawić właściwość negotiateClientCertificate na wartość true ("negotiateClientCertificate": "true") w nazwie hosta bramy. W portalu zaznacz pole wyboru Negocjuj certyfikat klienta .

Jeśli właściwość ma wartość true, certyfikat klienta jest wymagany w czasie połączenia SSL/TLS przed wymianą żądań HTTP. Ponieważ ustawienie ma zastosowanie na poziomie nazwy hosta bramy, wszystkie żądania połączenia wymagają certyfikatu klienta. Możesz obejść to ograniczenie i skonfigurować do 20 domen niestandardowych dla Gateway (obsługiwane wyłącznie w warstwie Premium).

Ograniczenie dotyczące niestandardowej nazwy domeny w warstwach v2

Obecnie w warstwach Standardowa v2 i Premium v2 usługa API Management wymaga publicznie rozpoznawalnej nazwy DNS, aby zezwolić na ruch do punktu końcowego bramy. Jeśli skonfigurujesz niestandardową nazwę domeny dla punktu końcowego bramy, ta nazwa musi być publicznie rozpoznawana, a nie ograniczona do prywatnej strefy DNS.

Aby obejść ten problem w scenariuszach, w których ograniczasz publiczny dostęp do bramy i konfigurujesz nazwę domeny prywatnej, możesz skonfigurować usługę Application Gateway do odbierania ruchu w nazwie domeny prywatnej i kierować go do punktu końcowego bramy wystąpienia usługi API Management. Aby zapoznać się z przykładową architekturą, zobacz to repozytorium GitHub.

Rozwiązywanie problemów: rotacja certyfikatów nazwy hosta z usługi Azure Key Vault nie powiodła się

Z powodu zmiany konfiguracji lub problemu z łącznością instancja usługi API Management może nie być w stanie pobrać certyfikatu nazwy hosta z usługi Azure Key Vault po zaktualizowaniu lub odnowieniu certyfikatu. W takim przypadku instancja zarządzania API będzie nadal używać buforowanego certyfikatu, dopóki nie otrzyma zaktualizowanego certyfikatu. Jeśli buforowany certyfikat wygaśnie, ruch środowiska uruchomieniowego do bramy zostanie zablokowany. Każda usługa nadrzędna, taka jak Application Gateway, korzystająca z konfiguracji certyfikatu nazwy hosta, może również zablokować ruch w czasie działania do bramy, kiedy używany jest wygasły certyfikat buforowany.

Aby rozwiązać ten problem, upewnij się, że magazyn kluczy istnieje, a certyfikat jest przechowywany w magazynie kluczy. Jeśli wystąpienie usługi API Management zostało wdrożone w sieci wirtualnej, potwierdź łączność wychodzącą z tagiem usługi AzureKeyVault. Sprawdź, czy istnieje tożsamość zarządzana używana do uzyskiwania dostępu do magazynu kluczy. Potwierdź uprawnienia tożsamości zarządzanej w celu uzyskania dostępu do magazynu kluczy. Zapoznaj się z rozdziałem Konfigurowanie niestandardowej nazwy domeny – Key Vault, omówionym wcześniej w tym artykule, aby uzyskać szczegółowe instrukcje konfiguracji. Po przywróceniu konfiguracji certyfikat nazwy hosta zostanie odświeżony w usłudze API Management w ciągu 4 godzin.

Treści powiązane

Uaktualnianie i skalowanie usługi