Wyświetlasz dokumentację Apigee Edge.
Przejdź do
dokumentacji Apigee X. info
W tej sekcji opisujemy, jak za pomocą interfejsu Edge API tworzyć usługi API do publikowania w portalach dla programistów.
Tworzenie usług API za pomocą interfejsu API
Usługi API umożliwiają programistom rejestrowanie aplikacji, które korzystają z interfejsów API za pomocą kluczy interfejsu API i tokenów dostępu OAuth. Usługi API umożliwiają „grupowanie” zasobów interfejsu API, a następnie publikowanie tych pakietów w różnych grupach programistów. Może być na przykład konieczne opublikowanie jednego zestawu zasobów interfejsu API dla programistów partnerskich , a innego pakietu dla programistów zewnętrznych. Usługi API umożliwiają tworzenie takich pakietów na bieżąco, bez konieczności wprowadzania zmian w samych interfejsach API. Dodatkową zaletą jest to, że dostęp programistów można „ulepszać” i „obniżać” bez konieczności uzyskiwania przez programistów nowych kluczy konsumenta dla swoich aplikacji.
Aby utworzyć usługę API za pomocą interfejsu API, wyślij żądanie POST do
/organizations/{org_name}/apiproducts.
Więcej informacji znajdziesz w Create API Product dokumentacji API.
To żądanie tworzy usługę API o nazwie weather_free. Usługa API
zapewnia dostęp do wszystkich interfejsów API udostępnianych przez proxy interfejsu API o nazwie weatherapi, które jest
wdrożone w środowisku test. Typ zatwierdzenia jest ustawiony na auto, co oznacza, że każde
żądanie dostępu zostanie zatwierdzone.
curl -X POST https://api.enterprise.apigee.com/v1/organization/myorg/apiproducts \
-H "Content-Type:application/json" \
-d \
'{
"approvalType": "auto",
"displayName": "Free API Product",
"name": "weather_free",
"proxies": [ "weatherapi" ],
"environments": [ "test" ]
}' \
-u email:password
Przykładowa odpowiedź:
{ "apiResources" : [ ], "approvalType" : "auto", "attributes" : [ ], "createdAt" : 1362759663145, "createdBy" : "developer@apigee.com", "displayName" : "Free API Product", "environments" : [ "test" ], "lastModifiedAt" : 1362759663145, "lastModifiedBy" : "developer@apigee.com", "name" : "weather_free", "proxies" : [ "weatherapi" ], "scopes" : [ ] }
Utworzona powyżej usługa API implementuje najbardziej podstawowy scenariusz, czyli autoryzuje żądania do proxy interfejsu API w środowisku. Definiuje usługę API, która umożliwia autoryzowanej aplikacji dostęp do wszystkich zasobów interfejsu API, do których można uzyskać dostęp za pomocą proxy interfejsu API działającego w środowisku testowym. Usługi API udostępniają dodatkowe ustawienia konfiguracyjne, które umożliwiają dostosowanie kontroli dostępu do interfejsów API dla różnych grup programistów. Możesz na przykład utworzyć 2 usługi API, które zapewniają dostęp do różnych proxy interfejsu API. Możesz też utworzyć 2 usługi API, które zapewniają dostęp do tych samych proxy interfejsu API, ale z różnymi powiązanymi ustawieniami limitu.
Ustawienia konfiguracyjne usługi API
Usługi API udostępniają te opcje konfiguracji:
| Nazwa | Opis | Domyślny | Wymagany? |
|---|---|---|---|
apiResources |
Lista rozdzielona przecinkami adresów URI lub ścieżek do zasobów „spakowanych” w produkcie API. Domyślnie ścieżki do zasobów są mapowane z Możesz wybrać konkretną ścieżkę lub wszystkie podścieżki za pomocą symbolu wieloznacznego.
Symbole wieloznaczne (/** i /*) są obsługiwane. Symbol wieloznaczny z podwójną gwiazdką oznacza, że uwzględniane są wszystkie
podadresy URI. Pojedyncza gwiazdka oznacza, że uwzględniane są tylko adresy URI o jeden poziom niżej.
uwzględnione. |
Nie dotyczy | Nie |
approvalType |
Określa, jak klucze interfejsu API są zatwierdzane w celu uzyskania dostępu do interfejsów API zdefiniowanych przez usługę API. Jeśli
ustawisz wartość manual, klucz wygenerowany dla aplikacji będzie w stanie „oczekujący”.
Takie klucze nie będą działać, dopóki nie zostaną wyraźnie zatwierdzone. Jeśli ustawisz wartość auto,
wszystkie klucze są generowane w stanie 'zatwierdzony' i działają od razu. (auto jest
zwykle używane do zapewniania dostępu do bezpłatnych/testowych usług API, które mają ograniczony limit
lub możliwości). |
Nie dotyczy | Tak |
attributes |
Tablica atrybutów, których można użyć do rozszerzenia domyślnego profilu usługi API o metadane specyficzne dla klienta.
Użyj tej właściwości, aby określić poziom dostępu do usługi API jako publiczny, prywatny lub wewnętrzny. Na przykład:
"attributes": [
{
"name": "access",
"value": "public"
},
{
"name": "foo","value": "foo" }, { "name": "bar", "value": "bar" }
]
|
Nie dotyczy | Nie |
scopes |
Lista rozdzielona przecinkami zakresów OAuth, które są weryfikowane w czasie działania. (Apigee Edge sprawdza, czy zakresy w każdym przedstawionym tokenie dostępu są zgodne z zakresem ustawionym w usłudze API ). | Nie dotyczy | Nie |
proxies |
Nazwane proxy interfejsu API, z którymi jest powiązana ta usługa API. Określając proxy, możesz powiązać zasoby w usłudze API z konkretnymi proxy interfejsu API, uniemożliwiając programistom dostęp do tych zasobów za pomocą innych proxy interfejsu API. | Nie dotyczy | Nie. Jeśli nie jest zdefiniowana, apiResources należy wyraźnie zdefiniować (więcej informacji
znajdziesz powyżej), i ustawić zmienną flow.resource.name w
zasadzie AssignMessage.apiResources |
environments |
Nazwane środowiska (np. „test” lub „prod”), z którymi jest powiązana ta usługa API. Określając co najmniej 1 środowisko, możesz powiązać zasoby wymienione w usłudze API do konkretnego środowiska, uniemożliwiając programistom dostęp do tych zasobów za pomocą proxy interfejsu API w innym środowisku. To ustawienie służy na przykład do uniemożliwienia dostępu do zasobów powiązanych z proxy interfejsu API w środowisku „prod” przez proxy interfejsu API wdrożone w środowisku „test”. | Nie dotyczy | Nie. Jeśli nie jest zdefiniowana, apiResources należy wyraźnie zdefiniować i ustawić zmienną
flow.resource.name w zasadzie AssignMessage. |
quota |
Liczba żądań dozwolonych na aplikację w określonym przedziale czasu. | Nie dotyczy | Nie |
quotaInterval |
Liczba jednostek czasu, w których są oceniane limity. | Nie dotyczy | Nie |
quotaTimeUnit |
Jednostka czasu (minuta, godzina, dzień lub miesiąc), w której są zliczane limity. | Nie dotyczy | Nie |
Poniżej znajdziesz bardziej szczegółowy przykład tworzenia usługi API.
curl -X POST https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts \
-H "Content-Type:application/json" -d \
'{
"apiResources": [ "/forecastrss" ],
"approvalType": "auto",
"attributes":
[ {"name": "access", "value": "public"} ],
"description": "Free API Product",
"displayName": "Free API Product",
"name": "weather_free",
"scopes": [],
"proxies": [ "weatherapi" ],
"environments": [ "test" ],
"quota": "10",
"quotaInterval": "2",
"quotaTimeUnit": "hour" }' \
-u email:password
Przykładowa odpowiedź
{ "apiResources" : [ "/forecastrss" ], "approvalType" : "auto", "attributes" : [ { "name" : "access", "value" : "public" }, "createdAt" : 1344454200828, "createdBy" : "admin@apigee.com", "description" : "Free API Product", "displayName" : "Free API Product", "lastModifiedAt" : 1344454200828, "lastModifiedBy" : "admin@apigee.com", "name" : "weather_free", "scopes" : [ ], "proxies": [ {'weatherapi'} ], "environments": [ {'test'} ], "quota": "10", "quotaInterval": "1", "quotaTimeUnit": "hour"}' }
Informacje o zakresach
Zakres to pojęcie zaczerpnięte z OAuth, które odpowiada w przybliżeniu pojęciu „uprawnienia”. W Apigee Edge zakresy są całkowicie opcjonalne. Możesz używać zakresów, aby uzyskać bardziej szczegółową autoryzację. Każdy klucz konsumenta wydany aplikacji jest powiązany z „zakresem głównym”. Zakres główny to zbiór wszystkich zakresów we wszystkich usługach API, do których aplikacja ma dostęp. W przypadku aplikacji, które mają dostęp do wielu usług API, zakres główny jest sumą wszystkich zakresów zdefiniowanych w usługach API, do których klucz konsumenta ma dostęp.
Wyświetlanie usług API
Aby wyświetlić usługi API utworzone dla organizacji za pomocą interfejsu API, zapoznaj się z tymi sekcjami:
- Wyświetlanie usług API (spieniężonych)
Domyślnie wyświetlane są tylko spieniężone usługi API (czyli usługi API z co najmniej 1 opublikowanym planem stawek). Aby wyświetlić wszystkie usługi API, ustaw parametr zapytania
monetizednafalse. Jest to równoznaczne z wysłaniem żądania GET do interfejsu API List API products (nieobjętych monetyzacją):https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts?expand=true - Wyświetlanie usług API (nieobjętych monetyzacją)
- Wyświetlanie usług API, do których programista ma dostęp
- Wyświetlanie usług API, do których firma ma dostęp
Poniżej znajdziesz przykład wyświetlania usług API za pomocą interfejsu API:
curl -X GET "https://ext.apiexchange.org/v1/mint/organizations/{org_name}/products?monetized=true" \
-H "Accept:application/json" \
-u email:password
Odpowiedź powinna wyglądać mniej więcej tak (pokazana jest tylko część odpowiedzi):
{
"product" : [ {
"customAtt1Name" : "user",
"customAtt2Name" : "response size",
"customAtt3Name" : "content-length",
"description" : "payment api product",
"displayName" : "payment",
"id" : "payment",
"name" : "payment",
"organization" : {
...
},
"pricePoints" : [ ],
"status" : "CREATED",
"transactionSuccessCriteria" : "status == 'SUCCESS'"
}, {
"customAtt1Name" : "user",
"customAtt2Name" : "response size",
"customAtt3Name" : "content-length",
"description" : "messaging api product",
"displayName" : "messaging",
"id" : "messaging",
"name" : "messaging",
"organization" : ...
},
"pricePoints" : [ ],
"status" : "CREATED",
"transactionSuccessCriteria" : "status == 'SUCCESS'"
} ],
"totalRecords" : 2
}Rejestrowanie programistów za pomocą interfejsu API
Wszystkie aplikacje należą do programistów lub firm. Aby utworzyć aplikację, musisz najpierw zarejestrować programistę lub firmę.
Programiści są rejestrowani w organizacji przez utworzenie profilu. Pamiętaj, że adres e-mail programisty podany w profilu jest używany jako unikalny klucz programisty w Apigee Edge.
Aby obsługiwać monetyzację, musisz zdefiniować atrybuty monetyzacji podczas tworzenia lub edytowania programistów. Możesz też zdefiniować inne dowolne atrybuty do użycia w niestandardowych analizach, egzekwowaniu niestandardowych zasad itp. Te dowolne atrybuty nie będą interpretowane przez Apigee Edge,
Na przykład to żądanie rejestruje profil programisty, którego adres e-mail to
ntesla@theremin.com i definiuje podzbiór atrybutów monetyzacji
za pomocą interfejsu Create developer API:
$ curl -H "Content-type:application/json" -X POST -d \
'{"email" : "ntesla@theremin.com",
"firstName" : "Nikola",
"lastName" : "Tesla",
"userName" : "theremin",
"attributes" : [
{
"name" : "project_type",
"value" : "public"
},
{
"name": "MINT_BILLING_TYPE",
"value": "POSTPAID"
},
{
"name": "MINT_DEVELOPER_ADDRESS",
"value": "{\"address1\":\"Dev One Address\",\"city\":\"Pleasanton\",\"country\":\"US\",\"isPrimary\":true,\"state\":\"CA\",\"zip\":\"94588\"}"
},
{
"name": "MINT_DEVELOPER_TYPE",
"value": "TRUSTED"
},
{
"name": "MINT_HAS_SELF_BILLING,
"value": "FALSE"
},
{
"name" : "MINT_SUPPORTED_CURRENCY",
"value" : "usd"
}
]
}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers \
-u email:password
Przykładowa odpowiedź
{ "email" : "ntesla@theremin.com", "firstName" : "Nikola", "lastName" : "Tesla", "userName" : "theremin", "organizationName" : "{org_name}", "status" : "active", "attributes" : [ { "name" : "project_type", "value" : "public" }, { "name": "MINT_BILLING_TYPE", "value": "POSTPAID" }, { "name": "MINT_DEVELOPER_ADDRESS", "value": "{\"address1\":\"Dev One Address\",\"city\":\"Pleasanton\",\"country\":\"US\",\"isPrimary\":true,\"state\":\"CA\",\"zip\":\"94588\"}" }, { "name": "MINT_DEVELOPER_TYPE", "value": "TRUSTED" }, { "name": "MINT_HAS_SELF_BILLING, "value": "FALSE" }, { "name" : "MINT_SUPPORTED_CURRENCY", "value" : "usd" } ], "createdAt" : 1343189787717, "createdBy" : "admin@apigee.com", "lastModifiedAt" : 1343189787717, "lastModifiedBy" : "admin@apigee.com" }
Rejestrowanie aplikacji programistów za pomocą interfejsu API
Każda aplikacja zarejestrowana w Apigee Edge jest powiązana z programistą i usługą API. Gdy aplikacja jest rejestrowana w imieniu programisty, Apigee Edge generuje „dane logowania” (a klucz konsumenta i tajny klucz), które identyfikują aplikację. Aplikacja musi następnie przekazywać te dane logowania w ramach każdego żądania do usługi API powiązanej z aplikacją.
To żądanie używa interfejsu Create Developer App API do zarejestrowania aplikacji dla programisty utworzonego powyżej: ntesla@theremin.com. Podczas rejestrowania aplikacji definiujesz jej nazwę, adres callbackUrl i listę co najmniej 1 usługi API products:
$ curl -H "Content-type:application/json" -X POST -d \
'{
"apiProducts": [ "weather_free"],
"callbackUrl" : "login.weatherapp.com",
"keyExpiresIn" : "2630000000",
"name" : "weatherapp"}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps \
-u email:password
Adres callbackUrl jest używany przez
niektóre typy uwierzytelnienia przez OAuth (np. kod autoryzacji) do weryfikowania żądań przekierowania z aplikacji.
Jeśli używasz protokołu OAuth, ta wartość musi być taka sama jak redirect_uri
używana do wysyłania żądań protokołu OAuth.
Atrybut keyExpiresIn określa w milisekundach okres ważności klucza konsumenta, który zostanie wygenerowany dla aplikacji programisty. Wartość domyślna, -1, oznacza nieskończony okres ważności.
Przykładowa odpowiedź
{ "appId": "5760d130-528f-4388-8c6f-65a6b3042bd1", "attributes": [ { "name": "DisplayName", "value": "Test Key Expires" }, { "name": "Notes", "value": "Just testing this attribute" } ], "createdAt": 1421770824390, "createdBy": "wwitman@apigee.com", "credentials": [ { "apiProducts": [ { "apiproduct": "ProductNoResources", "status": "approved" } ], "attributes": [], "consumerKey": "jcAFDcfwImkJ19A5gTsZRzfBItlqohBt", "consumerSecret": "AX7lGGIRJs6s8J8y", "expiresAt": 1424400824401, "issuedAt": 1421770824401, "scopes": [], "status": "approved" } ], "developerId": "e4Oy8ddTo3p1BFhs", "lastModifiedAt": 1421770824390, "lastModifiedBy": "wwitman@apigee.com", "name": "TestKeyExpires", "scopes": [], "status": "approved" }
Zarządzanie kluczami konsumenta aplikacji za pomocą interfejsu API
Pobieranie klucza konsumenta (klucza interfejsu API) aplikacji
Dane logowania aplikacji (usługa API, klucz konsumenta i tajny klucz) są zwracane w ramach profilu aplikacji. Administrator organizacji może w każdej chwili pobrać klucz konsumenta.
Profil aplikacji wyświetla wartość klucza konsumenta i tajnego klucza, stan klucza konsumenta oraz wszystkie powiązania klucza z usługą API. Jako administrator możesz w każdej chwili pobrać profil klucza konsumenta za pomocą interfejsu Get Key Details for a Developer App API:
$ curl -X GET -H "Accept: application/json" \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J \
-u email:password
Przykładowa odpowiedź
{
"apiProducts" : [ {
"apiproduct" : "weather_free",
"status" : "approved"
} ],
"attributes" : [ ],
"consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
"consumerSecret" : "1eluIIdWG3JGDjE0",
"status" : "approved"
}Więcej informacji znajdziesz w artykule Get Key Details for a Developer App.
Dodawanie usługi API do aplikacji i klucza
Aby zaktualizować aplikację i dodać nową usługę API, dodaj ją do klucza aplikacji za pomocą interfejsu Add API Product to Key API. Więcej informacji znajdziesz w artykule Add API Product to Key.
Dodanie usługi API do klucza aplikacji umożliwia aplikacji, która ma ten klucz, dostęp do zasobów interfejsu API spakowanych w usłudze API. To wywołanie metody dodaje nową usługę API do aplikacji:
$ curl -H "Content-type:application/json" -X POST -d \
'{
"apiProducts": [ "newAPIProduct"]
}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J \
-u email:password
Przykładowa odpowiedź:
{
"apiProducts": [
{
"apiproduct": "weather_free",
"status": "approved"
},
{
"apiproduct": "newAPIProduct",
"status": "approved"
}
],
"attributes": [],
"consumerKey": "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
"consumerSecret": "1eluIIdWG3JGDjE0",
"expiresAt": -1,
"issuedAt": 1411491156464,
"scopes": [],
"status": "approved"
}
Zatwierdzanie kluczy konsumenta
Ustawienie typu zatwierdzenia na ręczne umożliwia kontrolowanie, którzy
programiści mogą uzyskiwać dostęp do zasobów chronionych przez usługi API. Gdy w przypadku usług API zatwierdzanie kluczy jest ustawione na manual, klucze konsumenta muszą zostać wyraźnie zatwierdzone. Klucze można
wyraźnie zatwierdzić za pomocą interfejsu Approve or Revoke Specific Key of Developer App
API:
$ curl -X POST -H "Content-type:appilcation/octet-stream" \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J?"action=approve" \
-u email:password
Przykładowa odpowiedź
{
"apiProducts" : [ {
"apiproduct" : "weather_free",
"status" : "approved"
} ],
"attributes" : [ ],
"consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
"consumerSecret" : "1eluIIdWG3JGDjE0",
"status" : "approved"
}Więcej informacji znajdziesz w artykule Approve or Revoke Specific Key of Developer App.
Zatwierdzanie usług API dla kluczy konsumenta
Powiązanie usługi API z kluczem konsumenta też ma stan. Aby dostęp do interfejsu API był możliwy, klucz konsumenta musi być zatwierdzony, oraz musi być zatwierdzony dla odpowiedniej usługi API. Powiązanie klucza konsumenta z usługą API można zatwierdzić za pomocą interfejsu Approve or Revoke API Product for a Key for a Developer App API:
$ curl -X POST -H "Content-type:application/octet-stream" \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=approve" \
-u email:password
To polecenie cURL nie zwraca odpowiedzi. Więcej informacji znajdziesz w artykule Approve or Revoke API Product for a Key for a Developer App.
Unieważnianie usług API dla kluczy konsumenta
Istnieje wiele powodów, dla których może być konieczne unieważnienie powiązania klucza konsumenta z usługą API produktu. Może być konieczne usunięcie usługi API z klucza konsumenta z powodu braku płatności ze strony programisty, wygaśnięcia okresu próbnego lub gdy aplikacja jest promowana z jednej usługi API do innej.
Aby unieważnić powiązanie klucza konsumenta z usługą API, użyj interfejsu Approve lub Revoke Specific Key of Developer App API, wykonując działanie revoke na kluczu konsumenta aplikacji programisty:
$ curl -X POST -H "Content-type:application/octet-stream" \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=revoke" \
-u email:password
To polecenie cURL nie zwraca odpowiedzi. Więcej informacji znajdziesz w artykule Approve or Revoke Specific Key of Developer App.
Egzekwowanie ustawień usługi API
Aby egzekwować usługi API, do przepływu proxy interfejsu API musi być dołączony jeden z tych typów zasad:
- VerifyAPIKey: pobiera odniesienie do klucza interfejsu API, sprawdza, czy reprezentuje on prawidłową aplikację, i dopasowuje go do usługi API. Więcej informacji znajdziesz w artykule Zasady weryfikacji klucza interfejsu API.
- OAuthV1, operacja „VerifyAccessToken”: weryfikuje podpis, sprawdza token dostępu OAuth 1.0a i „klucz konsumenta” oraz dopasowuje aplikację do usługi API. Więcej informacji znajdziesz w artykule Zasady OAuth w wersji 1.0a.
- OAuthV2, operacja „VerifyAccessToken”: sprawdza, czy token dostępu OAuth 2.0 jest prawidłowy, dopasowuje token do aplikacji, sprawdza, czy aplikacja jest prawidłowa, a następnie dopasowuje aplikację do usługi API. Więcej informacji znajdziesz na stronie głównej OAuth home.
Po skonfigurowaniu zasad i usług API Apigee Edge wykonuje te czynności:
- Apigee Edge otrzymuje żądanie i kieruje je do odpowiedniego proxy interfejsu API.
- Wykonuje się zasada, która weryfikuje klucz interfejsu API lub token dostępu OAuth przedstawiony przez klienta.
- Edge rozwiązuje klucz interfejsu API lub token dostępu do profilu aplikacji.
- Edge rozwiązuje listę (jeśli istnieje) usług API powiązanych z aplikacją.
- Pierwsza pasująca usługa API jest używana do wypełniania zmiennych limitu.
- Jeśli żadna usługa API nie pasuje do klucza interfejsu API lub tokena dostępu, żądanie jest odrzucane.
- Edge egzekwuje kontrolę dostępu opartą na adresach URI (środowisko, proxy interfejsu API i ścieżka URI) na podstawie ustawień usługi API oraz ustawień limitu.