Wdrażanie proxy interfejsu API za pomocą interfejsu API

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

Każda organizacja ma swój własny cykl życia tworzenia oprogramowania (SDLC). Często konieczne jest zsynchronizowanie i dostosowanie wdrożenia proxy interfejsu API do procesów używanych w przypadku usług backendu.

Metody Edge API przedstawione w tym artykule umożliwiają zintegrowanie zarządzania proxy interfejsu API z cyklem SDLC organizacji. Ten interfejs API jest często używany do pisania skryptów lub kodu które wdrażają proxy interfejsu API lub przenoszą je z jednego środowiska do drugiego w ramach większego zautomatyzowanego procesu, który wdraża lub przenosi też inne aplikacje.

Edge API nie zakłada niczego na temat Twojego cyklu SDLC (ani żadnego innego). Udostępnia natomiast funkcje atomowe, które mogą być koordynowane przez Twój zespół programistów w celu zautomatyzowania i zoptymalizowania cyklu życia tworzenia interfejsu API.

Pełne informacje znajdziesz w artykule Edge APIs.

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

• OAuth2 (tylko w chmurze publicznej)
• SAML (chmura publiczna i prywatna)
• Uwierzytelnianie podstawowe (niezalecane; chmura publiczna i prywatna)

Ten artykuł skupia się na zbiorze interfejsów API służących do zarządzania proxy interfejsu API.

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

Interakcja z interfejsem API

Te czynności przeprowadzą Cię przez proste interakcje z interfejsami API.

Wyświetlanie listy interfejsów API w organizacji

Możesz zacząć od wyświetlenia listy wszystkich proxy interfejsu API w organizacji. (Pamiętaj, aby zastąpić wpisy dla EMAIL:PASSWORD i ORG_NAME. Instrukcje znajdziesz w artykule Korzystanie z Edge API.

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

Przykładowa odpowiedź:

[ "weatherapi" ]

Pobieranie interfejsu API

Możesz wywołać metodę GET w przypadku dowolnego proxy interfejsu API w organizacji. To wywołanie zwraca listę wszystkich dostępnych wersji 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" ]
}

Jedynym szczegółem zwracanym przez tę metodę jest nazwa proxy interfejsu API wraz z powiązaną wersją, która ma przypisany numer. Proxy interfejsu API składają się z pakietu plików konfiguracyjnych files. Wersje zapewniają prosty mechanizm zarządzania aktualizacjami konfiguracji podczas iteracji. Wersje są numerowane kolejno, co umożliwia przywrócenie zmiany przez wdrożenie poprzedniej wersji proxy interfejsu API. Możesz też wdrożyć wersję proxy interfejsu API w środowisku produkcyjnym , a jednocześnie tworzyć nowe wersje tego proxy w środowisku testowym. Gdy wszystko będzie gotowe, możesz promować wyższą wersję proxy interfejsu API ze środowiska testowego do poprzedniej wersji proxy interfejsu API w środowisku produkcyjnym.

W tym przykładzie jest tylko 1 wersja, ponieważ proxy interfejsu API zostało dopiero utworzone. Gdy proxy interfejsu API przechodzi przez cykl życia iteracyjnego konfigurowania i wdrażania, numer wersji zwiększa się o liczby całkowite. Za pomocą bezpośrednich wywołań interfejsu API do wdrożenia możesz opcjonalnie zwiększyć numer wersji proxy interfejsu API. Czasami, gdy wprowadzasz drobne zmiany, możesz nie chcieć zwiększać wersji.

Pobieranie wersji interfejsu API

Wersja interfejsu API (np. api.company.com/v1) powinna się zmieniać bardzo rzadko. Gdy zwiększysz wersję interfejsu API, oznacza to dla programistów, że nastąpiła znacząca zmiana w sygnaturze interfejsu zewnętrznego udostępnianego przez interfejs API.

_Wersja_ proxy interfejsu API to zwiększany numer powiązany z konfiguracją proxy interfejsu API. Usługi API utrzymują wersje konfiguracji, dzięki czemu możesz przywrócić a konfigurację, gdy coś pójdzie nie tak. Domyślnie wersja proxy interfejsu API jest automatycznie zwiększana za każdym razem, gdy importujesz proxy interfejsu API za pomocą interfejsu Import an API proxy API. Jeśli nie chcesz zwiększać wersji proxy interfejsu API, użyj interfejsu Update API proxy revision API. Jeśli do wdrożenia używasz Maven, użyj opcji clean lub update zgodnie z opisem w pliku Maven plugin readme.

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

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"
}

Te elementy konfiguracji proxy interfejsu API są szczegółowo opisane w dokumentacji API proxy configuration reference.

Wdrażanie interfejsu API w środowisku

Gdy proxy interfejsu API zostanie skonfigurowane do prawidłowego odbierania i przekazywania żądań, możesz je wdrożyć w co najmniej 1 środowisku. Zwykle iterujesz proxy interfejsu API w środowisku test, a następnie, gdy wszystko jest gotowe, promujesz wersję proxy interfejsu API do środowiska prod. Często okazuje się, że w środowisku testowym masz znacznie więcej wersji proxy interfejsu API, głównie dlatego, że w środowisku produkcyjnym będziesz przeprowadzać znacznie mniej iteracji.

Proxy interfejsu API nie można wywołać, dopóki nie zostanie wdrożone w środowisku. Gdy wdrożysz wersję proxy interfejsu API w środowisku produkcyjnym, możesz opublikować adres URL prod dla deweloperów zewnętrznych.

Jak wyświetlić listę środowisk

Każda organizacja w Apigee Edge ma co najmniej 2 środowiska: test i prod. To rozróżnienie jest arbitralne. Chodzi o to, aby zapewnić Ci obszar, w którym możesz sprawdzić, czy proxy interfejsu API działa prawidłowo, zanim udostępnisz je deweloperom zewnętrznym.

Każde środowisko to tak naprawdę tylko adres sieciowy, który umożliwia oddzielenie ruchu między proxy interfejsu API, nad którymi pracujesz, a tymi, do których aplikacje uzyskują dostęp w czasie działania.

Środowiska zapewniają też segregację danych i zasobów. Możesz na przykład skonfigurować różne pamięci podręczne w środowiskach testowym i produkcyjnym, do których dostęp będą miały tylko proxy interfejsu API działające w tym środowisku.

Wyświetlanie środowisk w an organizacji

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

Przykładowa odpowiedź

[ "test", "prod" ]

Przeglądanie wdrożeń

Wdrożenie to wersja proxy interfejsu API, która została wdrożona w środowisku. Proxy interfejsu API w stanie wdrożonym jest dostępne w sieci pod adresami zdefiniowanymi w elemencie <VirtualHost> dla tego środowiska.

Wdrażanie proxy interfejsu API

Proxy interfejsu API nie można wywołać, dopóki nie zostanie wdrożone. Usługi API udostępniają interfejsy API typu REST które umożliwiają sterowanie procesem wdrażania.

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

Wyświetlasz dokumentację Apigee Edge.
Przejdź do dokumentacji Apigee X. info

Najpierw wycofaj wdrożenie istniejącej wersji. Określ nazwę środowiska i numer wersji proxy interfejsu API, którego wdrożenie 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 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

Bezproblemowe wdrożenie (bez przestojów)

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

Nie możesz wdrożyć jednej wersji proxy interfejsu API na innej. Najpierw trzeba wycofać wdrożenie pierwszej. Ustawiając override na true, wskazujesz, że jedna wersja proxy interfejsu API ma zostać wdrożona na obecnie wdrożonej wersji. W rezultacie kolejność wdrażania jest odwrócona – wdrażana jest nowa wersja, a po zakończeniu wdrażania wycofywane jest wdrożenie już wdrożonej wersji.

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

Możesz dodatkowo zoptymalizować wdrożenie, ustawiając parametr delay. Parametr delay określa przedział czasu w sekundach, po którym należy wycofać wdrożenie poprzedniej wersji. W efekcie transakcje w toku mają przedział czasu, w którym mogą się zakończyć, zanim zostanie wycofane wdrożenie proxy interfejsu API przetwarzającego transakcję. Oto, co się dzieje, gdy ustawisz override=true i parametr delay:

• Wersja 1 obsługuje żądania.
• Wersja 2 jest wdrażana równolegle.
• Gdy wersja 2 zostanie w pełni wdrożona, nowy ruch jest wysyłany do wersji 2. Do wersji 1 nie jest wysyłany żaden nowy ruch.
• Wersja 1 może jednak nadal przetwarzać istniejące transakcje. Ustawiając parametr delay (np. na 15 sekund), dajesz wersji 1 15 sekund na dokończenie przetwarzania istniejących transakcji.
• Po upływie przedziału opóźnienia wycofywane jest wdrożenie wersji 1.

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

Gdy używasz override=true wraz z parametrem delay, możesz wyeliminować odpowiedzi HTTP 5XX podczas wdrażania. Dzieje się tak, ponieważ obie wersje proxy interfejsu API są wdrażane jednocześnie, a starsza wersja jest wycofywana po upływie opóźnienia.

Wyświetlanie wszystkich wdrożeń wersji interfejsu API

Czasami trzeba pobrać listę wszystkich obecnie wdrożonych wersji 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"
}

Odpowiedź powyżej zawiera wiele właściwości specyficznych dla infrastruktury wewnętrznej Apigee Edge. Jeśli nie używasz Apigee Edge w wersji lokalnej, nie możesz zmienić tych ustawień.

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

Wyświetlanie wszystkich wdrożeń w środowisku testowym

Za pomocą tego wywołania możesz też pobrać stan wdrożenia w określonym środowisku (w tym numer wersji obecnie wdrożonego proxy interfejsu API):

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

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

Wyświetlanie wszystkich wdrożeń w organizacji

Aby pobrać listę wszystkich obecnie wdrożonych wersji wszystkich 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 ten sam wynik co powyżej w przypadku wszystkich proxy interfejsu API wdrożonych we wszystkich środowiskach.

Ponieważ interfejs API jest typu REST, możesz po prostu użyć metody POST wraz z ładunkiem JSON lub XML w odniesieniu do tego samego zasobu, aby utworzyć proxy interfejsu API.

Generowany jest profil proxy interfejsu API. Domyślna reprezentacja proxy interfejsu API jest w formacie JSON (JavaScript Object Notation). Poniżej znajduje się domyślna odpowiedź JSON na żądanie POST powyżej, które utworzyło proxy interfejsu API o nazwie weatherapi. Poniżej znajdziesz opis każdego elementu 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 proxy interfejsu API przedstawia pełną strukturę proxy interfejsu API:

• APIProxy revision: kolejno numerowana iteracja konfiguracji proxy interfejsu API, utrzymywana przez usługi API.
• APIProxy name: unikalna nazwa proxy interfejsu API.
• ConfigurationVersion: wersja usług API, z którą jest zgodna konfiguracja proxy interfejsu API .
• CreatedAt: czas wygenerowania proxy interfejsu API w formacie czasu uniksowego.
• CreatedBy: adres e-mail użytkownika Apigee Edge, który utworzył proxy interfejsu API .
• DisplayName: przyjazna dla użytkownika nazwa proxy interfejsu API.
• LastModifiedAt: czas wygenerowania proxy interfejsu API w formacie czasu uniksowego .
• LastModifiedBy: adres e-mail użytkownika Apigee Edge, który utworzył proxy interfejsu API
• Policies: lista zasad dodanych do tego proxy interfejsu API.
• ProxyEndpoints: lista nazwanych punktów końcowych proxy.
• Resources: lista zasobów (JavaScript, Python, Java, XSLT), które można wykonać w tym proxy interfejsu API .
• TargetServers: lista nazwanych serwerów docelowych (które można utworzyć za pomocą interfejsu Management API) używanych w zaawansowanych konfiguracjach do równoważenia obciążenia.
• TargetEndpoints: lista nazwanych punktów końcowych docelowych.

Pamiętaj, że wiele elementów konfiguracji proxy interfejsu API utworzonych za pomocą prostej metody POST powyżej jest pustych. W kolejnych artykułach dowiesz się, jak dodawać i konfigurować kluczowe komponenty proxy interfejsu API.

O tych elementach konfiguracji możesz też przeczytać w dokumentacji API proxy configuration reference.

Tworzenie skryptów dla interfejsu API

W artykule Using the sample API proxies, dostępnym na GitHubie znajdziesz skrypty powłoki, które otaczają narzędzie do wdrażania Apigee. Jeśli z jakiegoś powodu nie możesz użyć narzędzia do wdrażania w Pythonie, możesz wywołać interfejs API bezpośrednio. Obie metody są przedstawione w przykładowych skryptach poniżej.

Otaczanie narzędzia do wdrażania

Najpierw upewnij się, że narzędzie do wdrażania w Pythonie jest dostępne w Twoim środowisku lokalnym.

Następnie utwórz plik do przechowywania danych logowania. Skrypty wdrażania, które napiszesz, będą importować te ustawienia, co ułatwi Ci centralne zarządzanie danymi logowania do konta. W przykładzie platformy interfejsów API ten plik nazywa się 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 ustawienia skryptom powłoki, które otaczają 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 artykule Apigee API platform samples).

#!/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 pracę, utwórz też skrypt do wywoływania i testowania interfejsu API, jak poniżej:

#!/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

Warto napisać proste skrypty powłoki, które zautomatyzują proces przesyłania i wdrażania proxy interfejsu API.

Poniższy skrypt bezpośrednio wywołuje interfejs Management API. Wycofuje wdrożenie istniejącej wersji proxy interfejsu API, którą aktualizujesz, tworzy plik ZIP z katalogu /apiproxy zawierającego pliki konfiguracyjne 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