Jak aktualizovat Apigee Developer Portal API

Úvod

Apigee je platforma pro správu rozhraní API, která nabízí integrovaný portál pro vývojáře pro dokumentaci vystavených koncových bodů v proxy serverech API. To umožňuje vývojářům snadno komunikovat s API a seznámit se s nimi bez přílišné složitosti.

Všechna rozhraní API se mohou změnit, a proto se musí portál Apigee Developer Portal změnit, aby odrážel tyto aktualizace. Ruční aktualizace specifikace API se však rychle stává složitým úkolem.

Tento článek vysvětluje, jak automatizovat proces aktualizace rozhraní API v Apigee.

Předpoklady

• Apigee Developer Portal

Automatická aktualizace Apigee Developer Portal API

Aby se specifikace API objevila na Apigee Developer Portal, jsou nutné tři věci:

• Specifikace Open API , zkráceně označovaný jako soubor spec. V našem případě používáme klasický Pet Store.
• Produkt API – toto je sbírka rozhraní API. Protože s nimi pracuje Apigee Developer Portal, vytvoříme jeden pro zobrazení našich API. Pro demonstrační účely bude mít náš produkt API pouze jedno rozhraní API.
• Stávající portál pro vývojáře k publikování nebo aktualizaci produktu API a specifikace.

Níže uvedené sekce vysvětlují, jak automatizovat proces aktualizace API na Apigee.

Krok 1:Nahrání specifikace API

V současné době Apigee neposkytuje žádné prostředky pro nahrání specifikace API prostřednictvím rozhraní Admin API. Použijte uživatelské rozhraní Apigee k přidání nebo aktualizaci specifikací API.

1. Vyberte Importovat soubor možnost importovat specifikaci Pet Store. Při tom mějte otevřené nástroje Chrome DevTools (nebo ekvivalentní).

2. Měli byste vidět specifikaci API (v tomto příkladu „petshop“), jako na obrázku níže.

3. Specifikace API byla úspěšně nahrána. Podívejme se na síť, co se stalo na pozadí v Chrome DevTools.

K přidání specifikace API jsou potřeba maximálně tři volání API:

• POST
• PUT
• GET

POST, PUT a GET volání API

Níže je první volání API:

POST https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc

{
  "folder": "173137",
  "kind": "Doc",
  "name": "petstore"
}

• folder :ID složky se specifikacemi vaší organizace. To bude vždy stejné, protože každá organizace má jednu složku se specifikacemi a ta se nikdy nemění.
• kind :V tomto případě to bude vždy Doc protože nahráváme dokument.
• name :Název specifikace API. Ačkoli to není vynuceno, použijte jedinečný název, jinak může být při prohlížení specifikací API matoucí.

Výsledkem tohoto volání je vytvoření prázdné specifikace API se zadaným názvem. Očekávaná odpověď od Apigee je následující:

{
	"id": "299536",
	"kind": "Doc",
	"name": "petstore",
	"created": "2020-06-05T13:24:07.977Z",
	"creator": "/orgs/lukeb-eval",
	"modified": "2020-06-05T13:24:07.977Z",
	"permissions": null,
	"self": "/organizations/lukeb-eval/specs/doc/299536",
	"content": "/organizations/lukeb-eval/specs/doc/299536/content",
	"contents": null,
	"folder": "/organizations/lukeb-eval/specs/folder/173137",
	"folderId": "173137",
	"body": null,
	"trashed": false
}

Poznamenejte si id . Použijete jej v následujícím volání, abyste Apigee řekli, do kterého souboru potřebujeme vložit náš obsah:

PUT https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc/299536/content

Tělem požadavku pro toto volání je celá specifikace API YAML. Jako odpověď Apigee odpoví 200 OK , signalizuje, že specifikace API byla úspěšně nahrána.

Poslední hovor je:

GET https://apigee.com/dapi/api/organizations/lukeb-eval/specs/folder/home

Vygeneruje následující odpověď:

{
	"id": "173137",
	"kind": "Folder",
	"name": "/orgs/lukeb-eval root",
	"created": "2019-06-06T07:39:58.805Z",
	"creator": "/orgs/lukeb-eval",
	"modified": "2019-06-06T07:39:58.805Z",
	"permissions": null,
	"self": "/organizations/lukeb-eval/specs/folder/173137",
	"content": null,
	"contents": [{
		"id": "299536",
		"kind": "Doc",
		"name": "petstore",
		"created": "2020-06-05T13:24:07.977Z",
		"creator": "/orgs/lukeb-eval",
		"modified": "2020-06-05T13:24:08.740Z",
		"permissions": null,
		"self": "/organizations/lukeb-eval/specs/doc/299536",
		"content": "/organizations/lukeb-eval/specs/doc/299536/content",
		"contents": null,
		"folder": "/organizations/lukeb-eval/specs/folder/173137",
		"folderId": "173137",
		"body": null,
		"trashed": false
	}],
	"folder": null,
	"folderId": null,
	"body": null,
	"trashed": false
}

V tuto chvíli víme, že soubory specifikací jsou v naší organizaci k dispozici. Toto je poslední provedené volání, protože Apigee potřebuje aktualizovat uživatelské rozhraní, aby po přidání nového zobrazilo nejnovější specifikace.

Toto volání se také provede, pokud otevřeme Specifikace kartu v Apigee.

Po vyřízení požadavků HTTP jsme nyní schopni automatizovat vytváření nebo aktualizaci specifikace:

• GET https://apigee.com/dapi/api/organizations/lukeb-eval/specs/folder/home – Tím získáme folderId . Potřebujeme to pro další hovor. Také uvádí, zda je potřeba specifikaci vytvořit nebo aktualizovat, v závislosti na tom, zda již existuje.
• POST https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc – Pokud specifikace neexistuje, provedeme toto volání a vytvoříme prázdný soubor.
• PUT https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc/299536/content – Vyplňte specifikaci nejnovějšími informacemi. V závislosti na tom, zda se jednalo o požadavek na vytvoření nebo aktualizaci, id specifikace lze získat z kroků 1 nebo 2.

Tyto kroky se odrážejí v našem automatizačním skriptu upload_spec.py . Tento skript vyžaduje pro úspěšné spuštění následující argumenty:

• name – Název specifikace, která bude nahrána do Apigee. Pokud toto není jedinečné, specifikace se stejným názvem v Apigee bude aktualizována.
• file – Cesta k souboru spec na vašem počítači.
• org – Název organizace v Apigee. https://apigee.com/organizations/johnd-eval/proxy má název organizace johnd-eval .
• username – Uživatelské jméno uživatele Apigee, kterého skript používá k načtení přístupového tokenu. Tento přístupový token se používá pro všechna volání REST prováděná skriptem. Platnost access_tokenu vyprší každých 12 hodin. Obvykle se zde používá vyhrazený uživatel automatizace.
• password – Heslo pro výše uvedené uživatelské jméno.

Chcete-li vytvořit nebo aktualizovat specifikaci pro výše uvedený příklad, použijte:

upload_spec.py --name petstore --file petstore.yaml --org lukeb-eval --username $APIGEE_USER --password $APIGEE_PASSWORD

Typický úspěšný výsledek získaný z našeho automatizačního kanálu by byl následující:

Krok 2:Nahrání produktu API

V rámci našeho úsilí o automatizaci jsme vytvořili upload_product.py , která využívá API pro správu Apigee k vytvoření nebo aktualizaci produktu API.

Pro úspěšné spuštění skriptu jsou vyžadovány následující argumenty:

• file – Soubor JSON představující produkt API, který má být vytvořen. Příklad, jak jej vytvořit, lze nalézt v sekci Create API Product nebo Update API Product v dokumentaci Apigee Management API. Název je v souboru JSON vždy povinný, protože se používá ke kontrole, zda produkt API existuje nebo ne. Pokud produkt API existuje, je aktualizován novým souborem JSON.
• org – Název organizace v Apigee.
• username – Uživatelské jméno uživatele Apigee, kterého skript používá k načtení přístupového tokenu.
• password – Heslo pro výše uvedené uživatelské jméno.

Lze jej provést následovně:

upload_api_product.py --file product_settings.json --org lukeb-eval --username $APIGEE_USER --password $APIGEE_PASSWORD

Typický úspěšný výsledek získaný z našeho automatizačního kanálu by byl následující:

Krok 3:Nahrání specifikace API na portál pro vývojáře

Aktualizace specifikace API neznamená, že Apigee Developer Portal automaticky zobrazí nejnovější a Apigee to nenabízí prostřednictvím svého API pro správu.

To lze provést ručně prostřednictvím uživatelského rozhraní, takže musíme prozkoumat, jaká volání rozhraní API se používají k vytváření nebo aktualizaci dokumentace rozhraní API na portálu pro vývojáře.

1. V rozhraní API části vašeho vybraného portálu v Apigee, klikněte na +API tlačítko:

2. Vyberte produkt API a specifikaci API. Nakonec přidejte název a popis rozhraní API a klikněte na Dokončit .

3. Stisknutím tlačítka Dokončit tlačítko vyzve k následujícímu HTTP volání:

POST https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs

{
	"title": "Pet Store",
	"description": "",
	"edgeAPIProductName": "Pet Store",
	"visibility": true,
	"anonAllowed": true,
	"requireCallbackUrl": false,
	"specId": "petstore",
	"specContent": "299536"
}

4. Pro zobrazení specifikace API na portálu potřebujete následující parametry:

• edgeAPIProductName – Název dříve vytvořeného produktu API.
• specId – Název dříve vytvořené specifikace.
• specContent – ID souboru dříve vytvořené specifikace.

Je matoucí, že specId je ve skutečnosti název specifikace a jeho jedinečnost není vynucena Apigee. V našem automatizačním skriptu předpokládáme, že specifikace je jedinečně pojmenována, což pomůže načíst specContent prostřednictvím specId dále.

Podívejme se, co dělá uživatelské rozhraní Apigee, když se změní specifikace. Pokud se aktualizuje specifikace Pet Store, na obrazovce rozhraní API na vývojářském portálu se zobrazí následující:

Kliknutím na Spravovat snímek specifikací žlutý obrázek vpravo, dostaneme následující obrazovku:

Klikněte na Aktualizovat snímek . To aktualizuje vývojářský portál nejnovějšími specifikacemi.

Automatizace požadavků API

K automatizaci procesu potřebujeme tři požadavky API:

GET https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs

První způsobí následující odpověď:

{
	"status": "success",
	"message": "all visible apidocs returned",
	"data": [{
		"id": 57782,
		"siteId": "lukeb-eval-portal",
		"title": "Pet Store",
		"description": "Pet Store Description",
		"visibility": true,
		"enrollment": null,
		"apiId": "pet-store",
		"edgeAPIProductName": "Pet Store",
		"specId": "petstore",
		"specContent": "299536",
		"specTitle": null,
		"snapshotExists": true,
		"snapshotModified": 1591371293000,
		"modified": 1591371290000,
		"anonAllowed": true,
		"imageUrl": null,
		"snapshotState": "OK_DOCSTORE",
		"requireCallbackUrl": false,
		"categoryIds": [],
		"productExists": true,
		"specModified": null,
		"snapshotOutdated": false,
		"snapshotSourceMissing": false
	}],
	"request_id": "1309320113",
	"error_code": null
}

Z hlediska automatizace vám tento požadavek poskytuje ID vývojářského portálu a uvádí všechny specifikace na portálu.

Po získání ID portálu potřebujeme následující volání API:

PUT https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs/57782

{
	"specId": "petstore",
	"imageUrl": null,
	"visibility": true,
	"anonAllowed": true,
	"description": "Pet Store Description"
}

Výše uvedené volání slouží k potvrzení základního nastavení API na portálu. ID 57782 na konci adresy URL požadavku je ID vývojářského portálu.

Po dokončení se provede další požadavek:

PUT https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs/57782/snapshot

Tento požadavek nemá žádné tělo a dává portálu Developer Portal pokyn k zobrazení nejnovější specifikace.

Se všemi těmito informacemi jsme nyní schopni automatizovat nasazení specifikací portálu následovně:

1. Použijte GET https://apigee.com/dapi/api/organizations/lukeb-eval/specs/folder/home abychom se ujistili, že specifikace, kterou chceme zobrazit, existuje.

2. Zahrňte GET https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs získat ID portálu a zkontrolovat, zda potřebujeme vytvořit nebo aktualizovat specifikaci v portálu.

• Pokud potřebujete vytvořit:

POST https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs

• Pokud potřebujete aktualizovat:

PUT https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs/57782

PUT https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs/57782/snapshot

Za tímto účelem upload_portal_documentation.py byl vytvořen automatizační skript. To vyžaduje následující parametry:

• file – Soubor JSON představující dokumentaci portálu API, která má být vytvořena. Příklad JSON je uveden dříve v tomto příspěvku. Od orgname a specId jsou poskytovány jako parametry, neměly by být součástí souboru JSON, jinak budou přepsány. specContent je načteno z specId poskytnuto, protože pracujeme na předpokladu, že název specifikace bude vždy jedinečný.
• portal – Úplný název portálu, kde chceme dokumentaci vytvořit. např. Pokud je portál přístupný přes https://johnd-eval-test.apigee.io, celý název portálu je johnd-eval-test .
• org – Stejné jako v upload_spec.py .
• username – Stejné jako v upload_spec.py .
• password – Stejné jako v upload_spec.py .

Lze jej provést následovně:

upload_portal_documentation.py --file portal_documentation_setup.json --org lukeb-eval --spec_name petstore --portal portal --username $APIGEE_USER --password $APIGEE_PASSWORD

Typický úspěšný výsledek získaný z našeho automatizačního kanálu by byl následující:

Krok 4:Integrace CI/CD potrubí

Tyto skripty máme v obrazu Dockeru, takže je velmi snadné importovat a spouštět ve vašem kanálu CI/CD.

Vezměme si například GitLab:

apigee-spec-deploy:
  image: ghcr.io/phoenixnap/apigee-automation:v1.0.0
  stage: spec-deploy
  variables:
    SPEC_NAME: petstore
    SPEC_PATH: petstore.yaml
    APIGEE_PRODUCT: product.json
    APIGEE_PORTAL_DOC: portal_documentation.json
  script:
    - /automation/upload_spec.py --name $SPEC_NAME --file $SPEC_PATH --org $ORG_NAME --username $APIGEE_USER --password $APIGEE_PASSWORD
    - /automation/upload_api_product.py --file $APIGEE_PRODUCT --org $ORG_NAME --username $APIGEE_USER --password $APIGEE_PASSWORD
    - /automation/upload_portal_documentation.py --file $APIGEE_PORTAL_DOC --org $ORG_NAME --spec_name $SPEC_NAME --portal $APIGEE_PORTAL --username $APIGEE_USER --password $APIGEE_PASSWORD

Vytvořili jsme úlohu s názvem apigee-spec-deploy , který stáhne obrázek apigee-automation z GitHub Packages a spustí tři python skripty, o kterých jsme zde diskutovali, s nezbytnými parametry.

Úloha GitLab se zastaví, pokud některý skript selže. Pokud k tomu dojde, zobrazí se ve výstupu podrobná chyba. To zaručuje, že kdykoli je skript spuštěn, budou k dispozici všechny potřebné informace z předchozích skriptů.