Wdrażanie proxy interfejsu API za pomocą interfejsu API

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

Każda organizacja ma unikalny cykl tworzenia oprogramowania (SDLC). Często konieczne jest synchronizowanie wdrożenia serwera proxy interfejsu API i dostosowania go do procesów używanych przez usługi backendu.

Metody interfejsu Edge API przedstawione w tym temacie mogą zostać użyte do integracji zarządzania serwerami proxy interfejsów API z SDLC organizacji. Ten interfejs API jest często używany do pisania skryptów lub kodu, które wdrażają serwery proxy API lub migrują serwery proxy API z jednego środowiska do drugiego w ramach większego automatycznego procesu, który wdraża lub przenosi też inne aplikacje.

Interfejs Edge API nie przyjmuje w tym przypadku żadnych założeń dotyczących SDLC (ani innych osób). Ujawniają natomiast funkcje atomowe, które mogą koordynować Twój zespół programistów, aby zautomatyzować i zoptymalizować cykl życia tworzenia interfejsów API.

Więcej informacji znajdziesz w artykule na temat interfejsów API Edge.

Aby używać interfejsu Edge API, musisz uwierzytelniać się w wywołaniach. Możesz to zrobić za pomocą jednej z tych metod:

Ten temat skupia się na zbiorach interfejsów API służących do zarządzania serwerami proxy interfejsów API.

Film: obejrzyj ten krótki film, aby dowiedzieć się, jak wdrożyć interfejs API.

Interakcja z interfejsem API

Poniższe kroki przeprowadzą Cię przez prostą interakcję z interfejsami API.

Wyświetlanie listy interfejsów API w organizacji

Możesz rozpocząć od wyświetlenia listy wszystkich serwerów proxy interfejsów API w organizacji. Zastąp wpisy zamiast EMAIL:PASSWORD i ORG_NAME. Instrukcje znajdziesz w artykule o korzystaniu z interfejsu Edge API.

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis

Przykładowa odpowiedź:

[ "weatherapi" ]

Pobierz interfejs API

Metodę GET możesz wywołać na dowolnym serwerze proxy interfejsu API w organizacji. To wywołanie zwraca listę wszystkich dostępnych wersji serwera proxy interfejsu API.

curl -u EMAIL:PASSWORD -H "Accept: application/json" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi

Przykładowa odpowiedź:

{
  "name" : "weatherapi",
  "revision" : [ "1" ]
}

Jedyna informacja zwracana przez tę metodę to nazwa serwera proxy interfejsu API i powiązana z nią wersja, która ma powiązany numer. Serwery proxy interfejsu API składają się z pakietu plików konfiguracji. Wersje zapewniają prosty mechanizm zarządzania aktualizacjami konfiguracji podczas iteracji. Wersje są kolejno numerowane, dzięki czemu możesz cofnąć zmianę przez wdrożenie poprzedniej wersji serwera proxy interfejsu API. Możesz też wdrożyć wersję serwera proxy interfejsu API w środowisku produkcyjnym i nadal tworzyć nowe wersje tego serwera proxy interfejsu API w środowisku testowym. Gdy wszystko będzie gotowe, możesz promować wyższą wersję serwera proxy interfejsu API ze środowiska testowego nad poprzednią wersją serwera proxy interfejsu API w środowisku produkcyjnym.

W tym przykładzie występuje tylko 1 wersja, ponieważ serwer proxy interfejsu API został właśnie utworzony. Gdy serwer proxy interfejsu API przechodzi przez cykl życia konfiguracji iteracyjnej i wdrażania, numer wersji zwiększa się o liczby całkowite. Używając bezpośrednich wywołań interfejsu API do wdrożenia, możesz opcjonalnie zwiększyć numer wersji serwera proxy interfejsu API. Czasami po wprowadzeniu drobnych zmian nie zalecamy zwiększania wersji.

Pobieranie wersji interfejsu API

Wersja interfejsu API (np. api.company.com/v1) powinna się zmieniać bardzo rzadko. Jeśli zwiększysz wersję interfejsu API, deweloperzy będą wiedzieć, że nastąpiła istotna zmiana w podpisie zewnętrznego interfejsu ujawnianego przez interfejs API.

Wersja serwera proxy interfejsu API to zwiększona liczba powiązana z konfiguracją serwera proxy interfejsu API. Usługi interfejsu API utrzymują wersje konfiguracji, dzięki czemu możesz cofnąć konfigurację, gdy coś pójdzie nie tak. Domyślnie wersja serwera proxy interfejsu API jest automatycznie zwiększana za każdym razem, gdy zaimportujesz serwer proxy interfejsu API przy użyciu interfejsu API Import an API proxy. Jeśli nie chcesz zwiększać wersji interfejsu API serwera proxy, użyj interfejsu API Aktualizacja wersji interfejsu API serwera proxy. Jeśli do wdrażania używasz Maven, użyj opcji clean lub update zgodnie z opisem w pliku Readme wtyczki Maven.

Aby uzyskać szczegółowy widok, możesz na przykład wywołać metodę GET w wersji 1 serwera proxy interfejsu API.

curl -u EMAIL:PASSWORD -H "Accept:application/json" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi/revisions/1

Przykładowa odpowiedź

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1343178905169,
  "createdBy" : "andrew@apigee.com",
  "lastModifiedAt" : 1343178905169,
  "lastModifiedBy" : "andrew@apigee.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

Elementy konfiguracji serwera proxy interfejsu API zostały szczegółowo opisane w dokumentacji dotyczącej konfiguracji serwera proxy interfejsu API.

Wdrażanie interfejsu API w środowisku

Gdy serwer proxy interfejsu API jest skonfigurowany do prawidłowego odbierania i przekazywania żądań, możesz go wdrożyć w jednym lub kilku środowiskach. Zwykle wykonuje się iterację z użyciem serwerów proxy interfejsu API w test, a następnie, gdy wszystko będzie gotowe, zmieniaj wersję serwera proxy interfejsu API na prod. Często zdarza się, że w środowisku testowym jest znacznie więcej wersji serwera proxy interfejsu API, głównie ze względu na to, że w środowisku produkcyjnym będziesz wykonywać znacznie mniej iteracji.

Serwera proxy interfejsu API nie można wywołać, dopóki nie zostanie wdrożony w środowisku. Po wdrożeniu wersji serwera proxy interfejsu API do środowiska produkcyjnego możesz opublikować adres URL prod dla programistów zewnętrznych.

Jak wyświetlić listę środowisk

Każda organizacja w Apigee Edge ma co najmniej 2 środowiska: test i prod. Rozróżnienie jest dowolne. Celem jest zapewnienie miejsca, w którym możesz sprawdzić, czy serwer proxy interfejsu API działa prawidłowo, zanim otworzysz go dla zewnętrznych programistów.

Każde środowisko jest po prostu adresem sieciowym, co umożliwia rozdzielenie ruchu między serwery proxy interfejsu API, nad którymi pracujesz, od tych, z których aplikacje korzystają w czasie działania.

Środowiska umożliwiają również segregację danych i zasobów. Możesz na przykład skonfigurować różne pamięci podręczne w środowisku testowym i produkcyjnym, do których dostęp mają tylko serwery proxy interfejsu API działające w tym środowisku.

Wyświetl środowiska w organizacji

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments

Przykładowa odpowiedź

[ "test", "prod" ]

Przeglądaj wdrożenia

Wdrożenie to wersja serwera proxy interfejsu API, która została wdrożona w środowisku. Serwer proxy interfejsu API jest dostępny w stanie wdrożonym przez sieć pod adresami określonymi w elemencie <VirtualHost> w danym środowisku.

Wdrażanie serwerów proxy interfejsów API

Proxy interfejsów API nie można wywoływać, dopóki nie zostaną wdrożone. Usługi API udostępniają interfejsy API typu REST, które zapewniają kontrolę nad procesem wdrażania.

W danym momencie w środowisku można wdrożyć tylko jedną wersję serwera proxy interfejsu API. Dlatego należy wycofać wdrożoną wersję. Możesz zdecydować, czy nowy pakiet ma zostać wdrożony jako nowa wersja, czy też zastąpi istniejącą.

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. informacje.

Najpierw wycofaj wdrożenie istniejącej wersji. Podaj nazwę środowiska i numer wersji serwera proxy interfejsu API, którą chcesz wycofać:

curl -X DELETE \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments \
  -u EMAIL:PASSWORD

Następnie wdróż nową wersję. Nowa wersja serwera proxy interfejsu API musi już istnieć: 

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments \
  -u EMAIL:PASSWORD

Płynne wdrażanie (brak przestojów)

Aby zminimalizować ryzyko przestoju podczas wdrażania, użyj parametru override w metodzie wdrażania i ustaw go na true.

Nie możesz wdrożyć jednej wersji serwera proxy interfejsu API nad inną wersją. Pierwsza musi być zawsze wycofana. Ustawienie override na true wskazuje, że 1 wersja serwera proxy interfejsu API powinna zostać wdrożona zamiast obecnie wdrożonej wersji. W wyniku tego sekwencja wdrożenia jest odwrócona – nowa wersja jest wdrożona, a po zakończeniu wdrożenia wdrożona wersja jest wycofywana.

Ten przykład ustawia wartość override, przekazując ją jako parametr formularza: 

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments" \
  -d "override=true" \
  -u EMAIL:PASSWORD

Aby jeszcze bardziej zoptymalizować wdrożenie, ustaw parametr delay. Parametr delay określa przedział czasu w sekundach, przed którym należy wycofać wdrożenie poprzedniej wersji. Efektem jest to, że transakcje emitowane mają przedział czasu, w którym kończą się zanim transakcja przetwarzana przez serwer proxy interfejsu API zostanie wycofana. Oto co dzieje się z elementem override=true i zbiorem parametrów delay:

  • Wersja 1 obsługuje żądania.
  • Wdrażam wersję 2 równolegle.
  • Po pełnym wdrożeniu wersji 2 nowy ruch jest kierowany do wersji 2. Do wersji 1 nie jest wysyłany żaden nowy ruch.
  • Jednak Wersja 1 może nadal przetwarzać istniejące transakcje. Gdy ustawisz parametr delay (np. 15 sekund), wersja 1 będzie mieć 15 sekund na zakończenie przetwarzania istniejących transakcji.
  • Po upływie okresu opóźnienia wersja 1 zostanie wycofana.
curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments?delay=15" \
  -d "override=true" \
  -u EMAIL:PASSWORD
Parametr zapytania Opis
override

Wartość domyślna to false (normalne zachowanie podczas wdrażania: istniejąca wersja jest niewdrożona, a następnie wdrażana jest nowa).

Ustaw jako true, aby zastąpić normalne działanie wdrożenia i zapewnić płynne wdrażanie. Istniejąca wersja pozostaje wdrożona podczas wdrażania nowej. Po wdrożeniu nowej wersji stara zostanie wycofana. Użyj w połączeniu z parametrem delay, aby kontrolować moment wycofania wdrożenia.
delay

Aby umożliwić zakończenie przetwarzania transakcji w istniejącej wersji przed jej wycofaniem (i wyeliminować możliwość zastosowania 502 Bad Gateway lub 504 Gateway Timeout errors), ustaw ten parametr na liczbę sekund, o jaką ma być opóźnione wycofanie wdrożenia. Nie ma ograniczeń co do liczby sekund, które możesz ustawić, i nie ma to wpływu na wydajność ustawienia dużej liczby sekund. Podczas opóźnienia nie jest wysyłany do starej wersji.

Wartość domyślna to 0 (zero) sekund. Jeśli override ma wartość prawda, a delay ma wartość 0, istniejąca wersja jest wycofywana natychmiast po wdrożeniu nowej wersji. Wartości ujemne są traktowane jako czas 0 (zero) sekund.

Jeśli jednocześnie używany jest override=true oraz delay, można wyeliminować odpowiedzi HTTP 5XX podczas wdrażania. Wynika to z tego, że obie wersje serwera proxy interfejsu API będą wdrażane jednocześnie, a starsza wersja zostanie wycofana po opóźnieniu.

Wyświetl wszystkie wdrożenia wersji interfejsu API

Czasami konieczne jest pobranie listy wszystkich obecnie wdrożonych wersji serwera proxy interfejsu API.

curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis/weatherapi/revisions/1/deployments \
  -u EMAIL:PASSWORD
{
  "aPIProxy" : "weatherapi",
  "environment" : [ {
    "configuration" : {
      "basePath" : "",
      "steps" : [ ]
    },
    "name" : "test",
    "server" : [ {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "90096dd1-1019-406b-9f42-fbb80cd01200"
    }, {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "7d6e2eb1-581a-4db0-8045-20d9c3306549"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "1619e2d7-c822-45e0-9f97-63882fb6a805"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "8a5f3d5f-46f8-4e99-b4cc-955875c8a8c8"
    } ],
    "state" : "deployed"
  } ],
  "name" : "1",
  "organization" : "org_name"
}

Powyższa odpowiedź zawiera wiele właściwości specyficznych dla infrastruktury wewnętrznej Apigee Edge. Tych ustawień nie możesz zmienić, chyba że korzystasz z lokalnego środowiska Apigee Edge.

Ważne właściwości zawarte w odpowiedzi to organization, environment, aPIProxy, name i state. Przeglądając te wartości właściwości, możesz potwierdzić, że określona wersja serwera proxy interfejsu API jest wdrożona w środowisku.

Wyświetl wszystkie wdrożenia w środowisku testowym

Możesz też pobrać stan wdrożenia określonego środowiska (w tym numer wersji obecnie wdrożonego serwera proxy interfejsu API) za pomocą tego wywołania:

curl -u EMAIL:PASSWORD
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/test/deployments

Zwraca to ten sam wynik co powyżej dla każdego interfejsu API wdrożonego w środowisku testowym

Wyświetl wszystkie wdrożenia w organizacji

Aby pobrać listę wszystkich obecnie wdrożonych wersji wszystkich serwerów proxy interfejsu API we wszystkich środowiskach, użyj tej metody interfejsu API:

curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/deployments \
  -u EMAIL:PASSWORD

Zwraca to taki sam wynik jak powyżej w przypadku wszystkich serwerów proxy interfejsów API wdrożonych we wszystkich środowiskach.

Interfejs API jest typu REST, więc możesz po prostu użyć metody POST wraz z ładunkiem JSON lub XML dla tego samego zasobu, aby utworzyć serwer proxy interfejsu API.

Zostanie wygenerowany profil serwera proxy interfejsu API. Domyślna reprezentacja serwera proxy interfejsu API znajduje się w notacji obiektów JavaScript (JSON). Poniżej znajdziesz domyślną odpowiedź JSON na powyższe żądanie POST, które spowodowało utworzenie serwera proxy interfejsu API o nazwie weatherapi. Oto opis każdego elementu w profilu:

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1357172145444,
  "createdBy" : "you@yourcompany.com",
  "displayName" : "weatherapi",
  "lastModifiedAt" : 1357172145444,
  "lastModifiedBy" : "you@yourcompany.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

Wygenerowany profil serwera proxy interfejsu API przedstawia pełną strukturę serwera proxy interfejsu API:

  • APIProxy revision: sekwencyjnie numerowana iteracja konfiguracji serwera proxy interfejsu API, zgodna z usługami interfejsu API.
  • APIProxy name: unikalna nazwa serwera proxy interfejsu API
  • ConfigurationVersion: wersja usług API, z którą zgodna jest konfiguracja serwera proxy interfejsu API
  • CreatedAt: czas wygenerowania serwera proxy interfejsu API (w formacie czasu UNIX)
  • CreatedBy: adres e-mail użytkownika Apigee Edge, który utworzył serwer proxy interfejsu API
  • DisplayName: przyjazna dla użytkownika nazwa serwera proxy interfejsu API
  • LastModifiedAt: czas wygenerowania serwera proxy interfejsu API (w formacie czasu UNIX)
  • LastModifiedBy: adres e-mail użytkownika Apigee Edge, który utworzył serwer proxy interfejsu API
  • Policies: lista zasad, które zostały dodane do tego serwera proxy interfejsu API
  • ProxyEndpoints: lista nazwanych punktów ProxyEndpoints
  • Resources: lista zasobów (JavaScript, Python, Java, Spanner), które można wykonać na tym serwerze proxy interfejsu API
  • TargetServers: lista nazwanych serwerów docelowych (którą można utworzyć za pomocą interfejsu API zarządzania) używana w zaawansowanych konfiguracjach do równoważenia obciążenia.
  • TargetEndpoints: lista o nazwie TargetEndpoints

Pamiętaj, że wiele elementów konfiguracji serwera proxy interfejsu API utworzonych za pomocą prostej metody POST powyżej jest pustych. Z kolejnych tematów dowiesz się, jak dodawać i konfigurować najważniejsze komponenty serwera proxy interfejsu API.

Informacje o tych elementach konfiguracji znajdziesz też w dokumentacji dotyczącej konfiguracji serwera proxy interfejsu API.

Skrypty z użyciem interfejsu API

Sekcja Korzystanie z przykładowych serwerów proxy interfejsu API dostępna na GitHubie udostępnia skrypty powłoki, które opakowują narzędzie do wdrażania Apigee. Jeśli z jakiegoś powodu nie możesz użyć narzędzia do wdrażania Pythona, możesz bezpośrednio wywołać ten interfejs API. Oba podejścia przedstawiono w przykładowych skryptach poniżej.

Dodawanie narzędzia do wdrażania

Najpierw sprawdź, czy narzędzie do wdrażania Pythona jest dostępne w środowisku lokalnym.

Następnie utwórz plik do przechowywania danych logowania. Napisane przez Ciebie skrypty wdrożenia zaimportują te ustawienia, co umożliwi Ci centralne zarządzanie danymi logowania do konta. W przykładowym interfejsie API Platform ten plik nosi nazwę setenv.sh.

#!/bin/bash

org="Your ORG on enterprise.apigee.com"
username="Your USERNAME on enterprise.apigee.com"

# While testing, it's not necessary to change the setting below
env="test"
# Change the value below only if you have an on-premise deployment
url="https://api.enterprise.apigee.com"
# Change the value below only if you have a custom domain
api_domain="apigee.net"

export org=$org
export username=$username
export env=$env
export url=$url
export api_domain=$api_domain

Powyższy plik udostępnia wszystkie Twoje ustawienia skryptom powłoki, które pakują narzędzie do wdrażania.

Teraz utwórz skrypt powłoki, który importuje te ustawienia i używa ich do wywoływania narzędzia do wdrażania. Przykład znajdziesz w przykładach platformy Apigee API.

#!/bin/bash

source path/to/setenv.sh

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Deploying $proxy to $env on $url using $username and $org

path/to/deploy.py -n {api_name} -u $username:$password -o $org -h $url -e $env -p / -d path/to/apiproxy

Aby ułatwić sobie życie, utwórz skrypt do wywoływania i testowania interfejsu API w następujący sposób:

#!/bin/bash

echo Using org and environment configured in /setup/setenv.sh

source /path/to/setenv.sh

set -x

curl "http://$org-$env.apigee.net/{api_basepath}"

Bezpośrednie wywoływanie interfejsu API

Proste skrypty powłoki, które automatyzują proces przesyłania i wdrażania serwerów proxy interfejsu API, mogą być przydatne.

Poniższy skrypt bezpośrednio wywołuje interfejs API zarządzania. Wycofuje on wdrożenie istniejącej wersji aktualizowanego serwera proxy interfejsu API, tworzy plik ZIP z katalogu /apiproxy zawierającego pliki konfiguracji serwera proxy, a następnie przesyła, importuje i wdraża konfigurację.

#!/bin/bash

#This sets the name of the API proxy and the basepath where the API will be available
api=api

source /path/to/setenv.sh

echo Delete the DS_store file on OSX

echo find . -name .DS_Store -print0 | xargs -0 rm -rf
find . -name .DS_Store -print0 | xargs -0 rm -rf

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Undeploy and delete the previous revision

# Note that you need to explicitly update the revision to be undeployed.
# One benefit of the Python deploy tool is that it manages this for you.

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X DELETE

curl -k -u $username:$password -X DELETE "$url/v1/o/$org/apis/$api/revisions/1"

rm -rf $api.zip

echo Create the API proxy bundle and deploy

zip -r $api.zip apiproxy

echo Import the new revision to $env environment 

curl -k -v -u $username:$password "$url/v1/o/$org/apis?action=import&name=$api" -T $api.zip -H "Content-Type: application/octet-stream" -X POST

echo Deploy the new revision to $env environment 

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X POST