Udostępnij za pośrednictwem

Wersje w usłudze Azure API Management

  • Artykuł

DOTYCZY: Wszystkie warstwy usługi API Management

Wersje umożliwiają wprowadzanie zmian w interfejsach API w kontrolowany i bezpieczny sposób. Jeśli chcesz wprowadzić zmiany, utwórz nową wersję. Następnie można edytować i testować interfejs API bez zakłócania pracy użytkowników tego interfejsu API. Gdy wszystko będzie gotowe, wprowadź bieżącą wersję. W tym samym czasie można opcjonalnie opublikować wpis w dzienniku zmian, aby użytkownicy interfejsu API byli na bieżąco z tym, co się zmieniło. Dziennik zmian jest publikowany w Twoim portalu deweloperów.

Uwaga

Portal dla deweloperów nie jest dostępny w warstwie Zużycie.

Dzięki poprawkom można wykonywać następujące czynności:

  • Sejf wprowadzać zmiany w definicjach i zasadach interfejsu API bez zakłócania produkcyjnego interfejsu API.
  • Wypróbuj zmiany przed ich opublikowaniem.
  • Dokumentuj wprowadzone zmiany, aby deweloperzy mogli zrozumieć, co nowego.
  • Wycofaj się, jeśli znajdziesz problemy.

Rozpocznij pracę z poprawkami, postępując zgodnie z naszym przewodnikiem.

Uzyskiwanie dostępu do określonych poprawek

Dostęp do każdej poprawki interfejsu API można uzyskać przy użyciu specjalnie sformułowanego adresu URL. Dołącz ;rev={revisionNumber} na końcu adresu URL interfejsu API, ale przed ciągiem zapytania, aby uzyskać dostęp do określonej poprawki tego interfejsu API. Na przykład możesz użyć tego adresu URL, aby uzyskać dostęp do wersji 3 interfejsu customers API:

https://apis.contoso.com/customers;rev=3/leads?customerId=123

Domyślnie każda poprawka ma te same ustawienia zabezpieczeń co bieżąca poprawka. Możesz celowo zmienić zasady dla określonej poprawki, jeśli chcesz zastosować różne zabezpieczenia dla każdej poprawki. Na przykład możesz dodać zasady filtrowania adresów IP, aby uniemożliwić zewnętrznym obiektom wywołującym uzyskanie dostępu do poprawki, która jest nadal opracowywana.

Uwaga

Element ;rev={id} musi być dołączany do identyfikatora interfejsu API, a nie do ścieżki identyfikatora URI.

Bieżąca poprawka

Jedną poprawkę można ustawić jako bieżącą poprawkę. Ta poprawka będzie używana dla wszystkich żądań interfejsu API, które nie określają jawnego numeru poprawki w adresie URL. Możesz przywrócić poprzednią wersję, ustawiając poprawkę jako bieżącą.

Możesz ustawić poprawkę jako bieżącą przy użyciu witryny Azure Portal. Jeśli używasz programu PowerShell, możesz użyć New-AzApiManagementApiRelease polecenia cmdlet .

Opisy poprawek

Podczas tworzenia poprawki można ustawić opis dla własnych celów śledzenia. Opisy nie są wyświetlane użytkownikom interfejsu API.

Po ustawieniu poprawki jako bieżącej można również opcjonalnie określić publiczną notatkę dziennika zmian. Dziennik zmian jest uwzględniony w portalu dla deweloperów, aby użytkownicy interfejsu API byli wyświetlani. Notatkę dziennika zmian można zmodyfikować przy użyciu Update-AzApiManagementApiRelease polecenia cmdlet programu PowerShell.

Uwaga

Jeśli edytujesz nieaktualną wersję interfejsu API, nie możesz zmienić następujących właściwości:

  • Nazwa
  • Pisz
  • Opis
  • Subskrypcja jest wymagana
  • Wersja interfejsu API
  • Opis wersji interfejsu API
  • Ścieżka
  • Protokoły

Te właściwości można zmienić tylko w bieżącej wersji. Jeśli zmiany zmienią dowolną z powyższych właściwości poprawki innej niż bieżąca, zostanie wyświetlony komunikat Can't change property for non-current revision o błędzie.

Przełącz poprawkę w tryb offline

Można przejąć poprawkę w tryb offline, co sprawia, że jest niedostępna dla osób wywołujących, nawet jeśli próbują uzyskać dostęp do poprawki za pośrednictwem adresu URL. Możesz oznaczyć poprawkę jako offline przy użyciu witryny Azure Portal.

Uwaga

Zalecamy przełącznie poprawek w tryb offline, gdy nie używasz ich do testowania.

Wersje i poprawki

Wersje i poprawki są odrębnymi funkcjami. Każda wersja może mieć wiele poprawek, podobnie jak interfejs API, który nie jest w wersji. Można używać poprawek bez używania wersji lub odwrotnie. Zazwyczaj wersje są używane do rozdzielania wersji interfejsu API zmianami powodujących niezgodność, podczas gdy poprawki mogą być używane do drobnych i niełamających się zmian w interfejsie API.

Jeśli okaże się, że poprawka zawiera zmiany powodujące niezgodność lub jeśli chcesz formalnie przekształcić poprawkę w wersję beta/testową, możesz utworzyć wersję na podstawie poprawki. W witrynie Azure Portal kliknij pozycję "Utwórz wersję z poprawki" w menu kontekstowym poprawek na karcie Poprawki.