Importowanie interfejsów API do centrum interfejsu API z usługi Azure API Management

  • Artykuł

W tym artykule przedstawiono sposób importowania (dodawania) interfejsów API z wystąpienia usługi Azure API Management do centrum interfejsu API przy użyciu interfejsu wiersza polecenia platformy Azure. Dodawanie interfejsów API z usługi API Management do spisu interfejsów API ułatwia ich odnajdywanie i dostęp do deweloperów, menedżerów programów interfejsów API i innych uczestników projektu w organizacji.

W tym artykule przedstawiono dwie opcje używania interfejsu wiersza polecenia platformy Azure do dodawania interfejsów API do centrum interfejsu API z usługi API Management:

Po zaimportowaniu definicji interfejsu API lub interfejsów API z usługi API Management możesz dodać metadane i dokumentację w centrum interfejsu API, aby ułatwić uczestnikom projektu odnajdywanie, zrozumienie i korzystanie z interfejsu API.

Wymagania wstępne

  • Centrum interfejsu API w ramach subskrypcji platformy Azure. Jeśli go nie utworzono, zobacz Szybki start: tworzenie centrum interfejsu API.

  • Co najmniej jedno wystąpienie usługi Azure API Management w tej samej lub innej subskrypcji. Podczas importowania interfejsów API bezpośrednio z usługi API Management wystąpienie usługi API Management i centrum interfejsu API muszą znajdować się w tym samym katalogu. Jeśli jeszcze go nie utworzono, zobacz Tworzenie wystąpienia usługi Azure API Management.

  • Co najmniej jeden interfejs API zarządzany w wystąpieniu usługi API Management, który chcesz dodać do centrum interfejsu API.

  • W przypadku interfejsu wiersza polecenia platformy Azure:

    Uwaga

    az apic Polecenia wymagają rozszerzenia interfejsu wiersza polecenia platformy apic-extension Azure. Jeśli nie użyto az apic poleceń, rozszerzenie jest instalowane dynamicznie po uruchomieniu pierwszego az apic polecenia. Dowiedz się więcej o rozszerzeniach interfejsu wiersza polecenia platformy Azure.

    Uwaga

    Przykłady poleceń interfejsu wiersza polecenia platformy Azure w tym artykule mogą być uruchamiane w programie PowerShell lub powłoce bash. W razie potrzeby ze względu na różne składnie zmiennych podano oddzielne przykłady poleceń dla dwóch powłok.

Opcja 1. Eksportowanie definicji interfejsu API z usługi API Management i importowanie jej do centrum interfejsu API

Najpierw wyeksportuj interfejs API z wystąpienia usługi API Management do definicji interfejsu API przy użyciu polecenia az apim api export . W zależności od scenariusza można wyeksportować definicję interfejsu API do pliku lokalnego lub adresu URL.

Eksportowanie interfejsu API do lokalnego pliku definicji interfejsu API

Poniższe przykładowe polecenie eksportuje interfejs API z identyfikatorem my-api w wystąpieniu interfejsu API myAPIManagement . Interfejs API jest eksportowany w formacie OpenApiJson do lokalnego pliku definicji interfejsu OpenAPI o nazwie specificationFile.json.

#! /bin/bash
az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonFile \
    --file-path "/path/to/folder"

#! PowerShell syntax
az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonFile `
    --file-path '/path/to/folder'

Eksportowanie interfejsu API do adresu URL

W poniższym przykładzie polecenie az apim api export eksportuje interfejs API z identyfikatorem my-api w formacie OpenApiJson do adresu URL w usłudze Azure Storage. Adres URL jest dostępny przez około 5 minut. W tym miejscu wartość adresu URL jest przechowywana w zmiennej $link .

#! /bin/bash
link=$(az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link \
    --output tsv)

# PowerShell syntax
$link=$(az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link `
    --output tsv)

Rejestrowanie interfejsu API w centrum interfejsu API z wyeksportowanej definicji interfejsu API

Nowy interfejs API można zarejestrować w centrum interfejsu API z wyeksportowanej definicji przy użyciu polecenia az apic api register .

Poniższy przykład rejestruje interfejs API w centrum interfejsu API myAPICenter z lokalnego pliku definicji interfejsu OpenAPI o nazwie definitionFile.json.

az apic api register --resource-group myResourceGroup --service myAPICenter --api-location "/path/to/definitionFile.json"

Importowanie definicji interfejsu API do istniejącego interfejsu API w centrum interfejsu API

W poniższym przykładzie użyto polecenia az apic api definition import-specification , aby zaimportować definicję interfejsu API do istniejącego interfejsu API w centrum interfejsu API myAPICenter . Tutaj definicja interfejsu API jest importowana z adresu URL przechowywanego w zmiennej $link .

W tym przykładzie założono, że masz interfejs API o nazwie my-api i skojarzonej wersji interfejsu API w wersji 1-0-0 i interfejsu API openapi jednostki definicji w centrum interfejsu API. Jeśli tego nie zrobisz, zobacz Dodawanie interfejsów API do centrum interfejsu API.

#! /bin/bash
az apic api definition import-specification \
    --resource-group myResourceGroup --service myAPICenter \
    --api-id my-api --version-id v1-0-0 \
    --definition-id openapi --format "link" --value '$link' \
    --specification '{"name":"openapi","version":"3.0.2"}'

# PowerShell syntax
az apic api definition import-specification `
    --resource-group myResourceGroup --service myAPICenter `
    --api-id my-api --version-id v1-0-0 `
    --definition-id openapi --format "link" --value '$link' `
    --specification '{"name":"openapi","version":"3.0.2"}'

Opcja 2. Importowanie interfejsów API bezpośrednio z wystąpienia usługi API Management

Poniżej przedstawiono kroki importowania interfejsów API z wystąpienia usługi API Management do centrum interfejsu API przy użyciu polecenia az apic service import-from-apim . To polecenie jest przydatne, gdy chcesz zaimportować wiele interfejsów API z usługi API Management do centrum interfejsu API, ale można go również użyć do zaimportowania pojedynczego interfejsu API.

Po dodaniu interfejsów API z wystąpienia usługi API Management do centrum interfejsu API przy użyciu polecenia az apic service import-from-apimnastępuje automatyczne wykonanie następujących czynności:

  • Wersje, definicje i informacje o wdrożeniu poszczególnych interfejsów API są kopiowane do centrum interfejsu API.
  • Interfejs API otrzymuje nazwę interfejsu API wygenerowaną przez system w centrum interfejsu API. Zachowuje swoją nazwę wyświetlaną (tytuł) z usługi API Management.
  • Etap cyklu życia interfejsu API jest ustawiony na Projekt.
  • Usługa Azure API Management jest dodawana jako środowisko.

Dodawanie tożsamości zarządzanej w centrum interfejsu API

W tym scenariuszu centrum interfejsów API używa tożsamości zarządzanej do uzyskiwania dostępu do interfejsów API w wystąpieniu usługi API Management. W zależności od potrzeb skonfiguruj przypisane przez system lub co najmniej jedną tożsamość zarządzaną przypisaną przez użytkownika.

W poniższych przykładach pokazano, jak skonfigurować tożsamość zarządzaną przypisaną przez system przy użyciu witryny Azure Portal lub interfejsu wiersza polecenia platformy Azure. Na wysokim poziomie kroki konfiguracji są podobne dla tożsamości zarządzanej przypisanej przez użytkownika.

  1. W portalu przejdź do centrum interfejsu API.
  2. W menu po lewej stronie w obszarze Zabezpieczenia wybierz pozycję Tożsamości zarządzane.
  3. Wybierz pozycję Przypisany system i ustaw stan na Wł.
  4. Wybierz pozycję Zapisz.

Przypisywanie tożsamości zarządzanej roli czytelnika usługi API Management

Aby zezwolić na importowanie interfejsów API, przypisz tożsamość zarządzaną centrum interfejsu API rolę Czytelnik usługi API Management w wystąpieniu usługi API Management. Możesz użyć portalu lub interfejsu wiersza polecenia platformy Azure.

  1. W portalu przejdź do wystąpienia usługi API Management.
  2. W menu po lewej stronie wybierz pozycję Kontrola dostępu (Zarządzanie dostępem i tożsamościami)..
  3. Wybierz pozycję + Dodaj przypisanie roli.
  4. Na stronie Dodawanie przypisania roli ustaw następujące wartości:
    1. Na karcie Rola — wybierz pozycję Czytelnik usługi API Management.
    2. Na karcie Członkowie w obszarze Przypisz dostęp do — wybierz pozycję Tożsamość> zarządzana+ Wybierz członków.
    3. Na stronie Wybieranie tożsamości zarządzanych — wybierz tożsamość zarządzaną przypisaną przez system centrum interfejsu API, która została dodana w poprzedniej sekcji. Kliknij opcję Wybierz.
    4. Wybierz Przejrzyj + przypisz.

Importowanie interfejsów API z usługi API Management

Użyj polecenia az apic service import-from-apim, aby zaimportować co najmniej jeden interfejs API z wystąpienia usługi API Management do centrum interfejsu API.

Uwaga

  • To polecenie zależy od tożsamości zarządzanej skonfigurowanej w centrum interfejsu API, która ma uprawnienia do odczytu do wystąpienia usługi API Management. Jeśli tożsamość zarządzana nie została dodana lub skonfigurowana, zobacz Dodawanie tożsamości zarządzanej w centrum interfejsu API wcześniej w tym artykule.

  • Jeśli centrum interfejsu API ma wiele tożsamości zarządzanych, polecenie wyszukuje najpierw tożsamość przypisaną przez system. Jeśli żadna z nich nie zostanie znaleziona, wybierze pierwszą tożsamość przypisaną przez użytkownika na liście.

Importowanie wszystkich interfejsów API z wystąpienia usługi API Management

Użyj symbolu wieloznakowego (*), aby określić wszystkie interfejsy API z wystąpienia usługi API Management.

  1. Pobierz identyfikator zasobu wystąpienia usługi API Management przy użyciu polecenia az apim show .

    #! /bin/bash
apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query id --output tsv)

    # PowerShell syntax
$apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query id --output tsv)

  2. Użyj polecenia , az apic service import-from-apim aby zaimportować interfejsy API. Zastąp nazwy centrum interfejsu API i grupą zasobów, a następnie użyj polecenia * , aby określić wszystkie interfejsy API z wystąpienia usługi API Management.

    az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apimID/apis/*

    Uwaga

    Jeśli wystąpienie usługi API Management ma dużą liczbę interfejsów API, importowanie do centrum interfejsu API może zająć trochę czasu.

Importowanie określonego interfejsu API z wystąpienia usługi API Management

Określ interfejs API do zaimportowania przy użyciu jego nazwy z wystąpienia usługi API Management.

  1. Pobierz identyfikator zasobu wystąpienia usługi API Management przy użyciu polecenia az apim show .

    #! /bin/bash
apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query id --output tsv)

    # PowerShell syntax
$apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query id --output tsv)

  2. Użyj polecenia , az apic service import-from-apim aby zaimportować interfejs API. Zastąp nazwy centrum interfejsu API i grupą zasobów, a następnie określ nazwę interfejsu API z wystąpienia usługi API Management.

    az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apimID/apis/<api-name>

    Uwaga

    Określ <api-name> nazwę zasobu interfejsu API w wystąpieniu usługi API Management, a nie nazwę wyświetlaną. Przykład: petstore-api zamiast Petstore API.

Po zaimportowaniu interfejsów API z usługi API Management można wyświetlać zaimportowane interfejsy API i zarządzać nimi w centrum interfejsów API.

Powiązana zawartość