如何更新Apigee Developer Portal API？分步操作指南

2021年11月20日17:39:22 发表评论 905 次浏览

Apigee Developer Portal API更新教程介绍

Apigee是一个 API 管理平台，它提供了一个集成的开发人员门户，用于记录 API 代理中公开的端点。这使开发人员能够轻松地与 API 交互并熟悉自己，而不会太复杂。

所有 API 都可能发生变化，因此，Apigee Developer Portal 需要进行更改以反映这些更新。但是，手动更新 API 规范很快就会变成一项复杂的任务。

本文介绍了如何在Apigee中自动化更新API的过程。

先决条件

  • Apigee 开发者门户

Apigee Developer Portal API 的自动更新

使 API 规范出现在 Apigee Developer Portal 中需要三件事：

  • Open API 规范，简称规范文件。在我们的例子中，我们使用的是经典的Pet Store。
  • 一个API产品-这是API的集合。由于 Apigee Developer Portal 与他们合作，我们将创建一个来显示我们的 API。出于演示目的，我们的 API 产品将只有一个 API。
  • 用于发布或更新 API 产品和规范的现有开发人员门户。

以下部分介绍了如何在 Apigee 上自动更新 API 的过程。

注意：脚本可以在 phoenixNAP 的GitHub repo 中找到。但是，我们建议使用托管在GitHub Packages上的图像，其中包含启动和运行所需的所有脚本和设置。

步骤 1：上传 API 规范

如何更新Apigee Developer Portal API？目前，Apigee 不提供任何通过 Admin API 上传 API 规范的方式。使用 Apigee 界面添加或更新 API 规范。

1. 选择导入文件选项以导入 Pet Store 规范。在执行此操作时打开 Chrome DevTools（或等效工具）。

如何更新Apigee Developer Portal API？分步操作指南

2. 你应该会看到列出的 API 规范（在本例中为“petshop”），如下图所示。

如何更新Apigee Developer Portal API？分步操作指南

3、API规范上传成功。让我们参考Chrome DevTools 中的Network选项卡，看看在后台发生了什么。

如何更新Apigee Developer Portal API？分步操作指南

添加 API 规范最多需要三个 API 调用：

  • POST
  • PUT
  • GET

POST、PUT 和 GET API 调用

下面是第一个 API 调用：

POST https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc
{
  "folder": "173137",
  "kind": "Doc",
  "name": "petstore"
}
  • folder：你组织的规范文件夹的 ID。这将始终相同，因为每个组织都有一个规范文件夹并且它永远不会改变。
  • kind：在这种情况下，它将始终是Doc因为我们正在上传文档。
  • name：API 规范的名称。尽管没有强制执行，但请使用唯一的名称，否则在查看 API 规范时可能会造成混淆。

此调用的结果是创建一个具有指定名称的空 API 规范。Apigee 的预期响应如下：

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

记下id. 你将在以下调用中使用它来告诉 Apigee 我们需要将内容放入哪个文件中：

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

此调用的请求正文是整个 API 规范YAML。作为响应，Apigee 将回复200 OK，表示 API 规范已成功上传。

最后一个电话是：

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

它产生以下响应：

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

如何在Apigee中自动化更新API？此时，我们知道规范文件在我们的组织中可用。这是最后一次执行的调用，因为 Apigee 在添加新规范后需要更新 UI 以显示最新规范。

如果我们只是在 Apigee 中打开Specs选项卡，也会执行此调用。

处理完 HTTP 请求后，我们现在可以自动创建或更新规范：

  • GET https://apigee.com/dapi/api/organizations/lukeb-eval/specs/folder/home– 这为我们提供了folderId. 我们需要它用于后续调用。它还指示是否需要创建或更新规范，具体取决于它是否已经存在。
  • POST https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc – 如果规范不存在，我们执行此调用以创建一个空文件。
  • PUT https://apigee.com/dapi/api/organizations/lukeb-eval/specs/doc/299536/content– 使用最新信息填写规范。根据是创建请求还是更新请求，id可以从步骤 1 或 2 中检索规范的 。

这些步骤反映在我们的自动化脚本upload_spec.py 中。此脚本需要以下参数才能成功运行：

  • name– 将上传到 Apigee 的规范名称。如果这不是唯一的，则 Apigee 中具有相同名称的规范将被更新。
  • file – 机器上规范文件的路径。
  • org– Apigee 中的组织名称。https://apigee.com/organizations/johnd-eval/proxies有组织名称johnd-eval。
  • username– 脚本用于获取访问令牌的 Apigee 用户的用户名。此访问令牌用于脚本执行的所有 REST 调用。access_token 每 12 小时到期一次。通常这里使用专门的自动化用户。
  • password–上述用户名的密码。

要为上述示例创建或更新规范，请使用：

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

从我们的自动化管道中获取的典型成功结果如下：

如何更新Apigee Developer Portal API？分步操作指南

步骤 2：上传 API 产品

如何更新Apigee Developer Portal API？在我们的自动化工作中，我们创建了upload_product.py，它利用 Apigee Management API 创建或更新 API 产品。

脚本成功运行需要以下参数：

  • file– 表示要创建的 API 产品的 JSON 文件。可以在 Apigee Management API 文档的创建 API 产品或更新 API 产品部分中找到如何创建它的示例。JSON 文件中的名称始终是必需的，因为它用于检查 API 产品是否存在。如果 API 产品存在，则会使用新的 JSON 文件进行更新。
  • org – Apigee 中的组织名称。
  • username – 脚本用于获取访问令牌的 Apigee 用户的用户名。
  • password – 上面提到的用户名的密码。

它可以按如下方式执行：

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

从我们的自动化管道中获取的典型成功结果如下：

如何更新Apigee Developer Portal API？分步操作指南

步骤 3：将 API 规范上传到开发者门户

Apigee Developer Portal API更新教程：更新 API 规范并不意味着 Apigee Developer Portal 会自动显示最新的规范，而且 Apigee 不会通过其管理 API 提供此功能。

这可以通过 UI 手动完成，因此我们需要调查使用哪些 API 调用来创建或更新 Developer Portal 上的 API 文档。

1. 在Apigee 中所选门户的API部分，点击+API按钮：

如何更新Apigee Developer Portal API？分步操作指南

2. 选择 API 产品和 API 规范。最后，为 API 添加名称和描述，然后单击Finish。

如何更新Apigee Developer Portal API？分步操作指南

3.按Finish 按钮提示如下HTTP调用：

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. 要在门户中显示 API 规范，你需要以下参数：

  • edgeAPIProductName – 之前创建的 API 产品的名称。
  • specId – 先前创建的规范的名称。
  • specContent – 先前创建的规范的文件 ID。

令人困惑的specId是，实际上是规范的名称，Apigee 并未强制执行其唯一性。在我们的自动化脚本，我们假设该规范是唯一命名的，这将有助于获取specContent通过specId 进一步上。

让我们考虑一下当规范发生变化时 Apigee UI 会做什么。如果 Pet Store 规范更新，以下内容将显示在 Developer Portal 的 API 屏幕上：

如何更新Apigee Developer Portal API？分步操作指南

通过单击 右侧的Manage Spec Snapshot黄色图像，我们得到以下屏幕：

如何更新Apigee Developer Portal API？分步操作指南

单击更新快照。这会使用最新的规范更新开发人员门户。

如何更新Apigee Developer Portal API？分步操作指南

自动化 API 请求

如何更新Apigee Developer Portal API？为了自动化这个过程，我们需要三个 API 请求：

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

首先，产生以下响应：

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

从自动化的角度来看，此请求为你提供了 Developer Portal 的 ID，并列出了门户上的所有规范。

获取门户ID后，我们需要进行如下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"
}

如何在Apigee中自动化更新API？上述调用用于确认门户上 API 的基本设置。请求 URL 末尾的 ID 57782是 Developer Portal 的 ID。

完成后，执行另一个请求：

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

此请求没有正文，它指示开发人员门户显示最新的规范。

有了所有这些信息，我们现在可以自动化门户规范部署，如下所示：

1. 用于GET https://apigee.com/dapi/api/organizations/lukeb-eval/specs/folder/home确保我们要显示的规范存在。

2. 包含GET https://apigee.com/portals/api/sites/lukeb-eval-portal/apidocs以获取门户 ID 并检查我们是否需要在门户中创建或更新规范。

  • 如果你需要创建：

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

  • 如果你需要更新：

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

为此，创建了upload_portal_documentation.py自动化脚本。这需要以下参数：

  • file– 表示要创建的 API 门户文档的 JSON 文件。JSON 的示例已在本博文之前显示。由于orgname 和specId 是作为参数提供的，因此它们不应成为 JSON 文件的一部分，否则它们将被覆盖。specContent 是从所specId 提供的中检索的，因为我们的工作前提是规范名称将始终是唯一的。
  • portal– 我们要在其中创建文档的门户的全名。例如，如果通过 https://johnd-eval-test.apigee.io 访问门户，则门户的全名是johnd-eval-test。
  • org– 与upload_spec.py相同。
  • username– 与upload_spec.py相同。
  • password– 与upload_spec.py相同。

它可以按如下方式执行：

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

从我们的自动化管道中获取的典型成功结果如下：

如何更新Apigee Developer Portal API？分步操作指南

第 4 步：CI/CD 管道集成

Apigee Developer Portal API更新教程：我们在Docker 映像中有这些脚本，因此很容易在CI/CD 管道中导入和执行它们。

我们以 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

我们创建了一个名为apigee-spec-deploy的管道作业，它从 GitHub 包中提取图像apigee-automation，并使用必要的参数执行我们在此处讨论的三个 python 脚本。

如果任何脚本失败，GitLab 作业将停止执行。如果发生这种情况，输出中会提供详细的错误。这保证了每当执行脚本时，它需要的来自先前脚本的所有信息都将可用。

结论

如何更新Apigee Developer Portal API？在本文中，你学习了如何通过创建脚本来利用 Apigee 界面中完成的调用或 Apigee 管理 API 中提供的调用，使你的 Apigee 开发者门户 API 保持最新状态。

这些脚本可以通过使用提供的 Docker 映像轻松集成到 CI/CD 管道中。有了这个，你的 Apigee 开发者门户将始终拥有最新的规范，而无需在每次更改时手动执行。

木子山

发表评论

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen: