创建可配置的 API 代理

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

借助可配置的^预览版 API 代理，Apigee 用户可以使用声明式配置创建和部署轻量级代理，这类似于 Kubernetes 资源模型。本页面介绍了创建可配置代理并使用新的基于归档的部署机制进行部署所需的步骤。

如需详细了解可配置的^预览版 API 代理，请参阅可配置的 API 代理。

可配置的^预览版 API 代理开发功能仅面向拥有 Apigee 付费组织的客户提供。拥有随用随付组织的 Apigee 客户则可以创建可编程 API 代理。

准备工作

本教程假设您已预配 Apigee 组织并安装 Apigee。否则，请参阅预配简介，了解安装和配置 Apigee 所需的步骤，然后再继续操作。

在开始学习本教程之前，请完成以下额外的步骤：

确认 Cloud SDK 已下载并安装到您的机器上。
下载 Cloud SDK
更新 gcloud 组件：
```
gcloud components update
```
确认您的 Apigee 凭据和组织详细信息，因为需要使用它们来为可配置的 API 代理预配环境。

预配 Apigee 环境

在创建代理配置之前，您必须预配一个支持可配置代理的 Apigee 环境。环境是组织中 API 代理和共享流的运行时执行上下文。您必须先将 API 代理部署到环境，然后才能对其进行访问。您可以将 API 代理部署到单个环境或多个环境。

如需了解详情，请参阅环境和环境组简介。

To create a new environment in the UI:

Open the Apigee UI in a browser.
Select Admin > Environments > Overview in the left navigation menu.
The UI displays a set of cards, each one representing an existing environment:

If this is your first time accessing the Environment view, there will be no environments.
Click +ENVIRONMENT.

The New environment dialog box displays:
Enter the following information in the New Environment dialog box:
1. Display name: A friendly name for the environment that is used in the UI. For example, My Test Environment.
2. Environment name: The programmatic name for the environment. This value will be part of the request URL for your API proxies and should not contain any spaces or other special characters. It can only letters, numbers, and hyphens. For example, my-environment-1.
  
  The new environment's name cannot be changed after it has been created.
3. Description (optional): Additional information about the environment that you want to add as a reminder.
4. Deployment type (Preview): Select Archive as the deployment type.
  Note: The deployment type used with this environment cannot be changed after the environment is created.
All fields except Description are required.
Click OK.

The card displays Pending Provisioning status while Apigee creates the new environment, as the following example shows:

There can be a several minute delay before the new environment is provisioned.

When it's done, the Apigee UI displays the new environment as a card with other environments that you have created:

将环境关联到 Apigee 实例

创建新环境后，您必须将新环境关联到 Apigee 实例才能进行访问。您可以在创建新实例时通过界面执行此操作（如果环境已存在）。在这种情况下，如果您之前已创建实例，则可以使用 Instances attachments create api 关联新环境。

如需查看该过程的示例，请参阅命令行配置文档中的创建环境。

在本教程中，您可以使用以下命令：

operation_name=$(curl -s -H "Authorization:Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/PROJECT_ID/instances/INSTANCE_NAME/attachments" \
  -X POST -H "content-type:application/json"\
  -d '{"environment":"ENV_NAME"}' | jq -r '.name' )

其中：

PROJECT_ID 是在其中创建 Apigee 环境的 Cloud 项目的 ID。此 ID 应与 Apigee 组织名称相同。
INSTANCE_NAME 是您的 Apigee 实例的名称。
ENV_NAME 是在其中部署可配置 API 代理的环境的名称。

此命令会返回一项长时间运行的操作。您可以使用以下命令轮询该操作，直到输出显示该操作为 done: true。

curl -s -H "Authorization:Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/$operation_name"

配置环境组

环境组（有时在 Apigee API 中称为 envgroup）是定义请求路由到各个环境的方式的基本机制。您可以在环境组（而不是单独的环境）中定义主机名，Apigee 使用这些主机名定义将请求路由到环境组中的环境。

未分配给环境组的环境没有指向它们的主机名，因此无法访问环境。如需了解详情，请参阅创建环境组。

如需为新环境配置环境组，请按照以下所述操作：

In the Apigee UI, select Admin > Environments > Groups.
Click +Environment Group:

The Add an Environment Group dialog displays.
Enter a name for your new environment group:

The name can contain only lower case letters, numbers, and hyphens. In addition, it must start with a letter, be at least two characters long, and cannot end with a hyphen. Valid names include my-env-group and prod2.
Click Add.
Apigee creates a new environment group. This is usually a very quick operation.

On a successful operation, Apigee confirms that the group has been created with a banner that looks like the following:

Apigee also assigns a default host name to the new group.
(Optional) Assign additional host names to the new group by clicking for that group.

Apigee displays the Environment group details pane:
Add host names to the Hostnames field. Each host name must be on a separate line.
Click Save when you're done.

You can add and remove host names to this list at any time using the same procedure.

创建代理归档

如需创建可配置的^预览版 API 代理归档，请执行以下操作：

在本地环境中，创建一个目录来将 Apigee 工作区存储在本地文件系统中。此目录将是可配置^预览版 API 代理文件结构的基础，如下所示：

.
└── src
    └── main
        └── apigee
            ├── apiproxies
            │   ├── <proxy-name>
            │   │   └── config.yaml
            │   ├── <proxy-name>
            │   │   └── config.yaml
            └── environments
                ├── <env-name>
                │   ├── deployments.json
                │   └── targetservers.json

mkdir -p SOURCE_DIR/src/main/apigee/apiproxies/PROXY_NAME

其中：

SOURCE_DIR 是归档目录的名称。
PROXY_NAME 是可配置代理的名称。

例如：

mkdir -p my-dir/src/main/apigee/apiproxies/my-proxy

使用以下命令为您的代理配置创建一个新文件：
```
vi SOURCE_DIR/src/main/apigee/apiproxies/PROXY_NAME/config.yaml
```
例如：
```
vi my-dir/src/main/apigee/apiproxies/my-proxy/config.yaml
```
您的代理配置文件必须使用以下文件名之一：
- config.yaml
- config.json
- config.yml

将以下代理配置复制到新的 config.yaml 文件中：

# config.yaml

basepath: "/helloworld"
operations:
- id: get-user
  http_match:
  - path_template: "/user"
    method: GET
target:
  uri: "https://mocktarget.apigee.net"

使用以下命令创建 deployments.json 文件：

vi SOURCE_DIR/src/main/apigee/environments/ENV_NAME/deployments.json

例如：

vi my-dir/src/main/apigee/environments/prod/deployments.json

将以下内容复制到 deployments.json 文件中：

{
  "proxies" : ["PROXY_NAME"]
}

如需查看更多示例，请参阅可配置的代理配置示例。

部署归档

如需将归档部署到 Apigee 环境，请使用以下 gcloud 命令：

gcloud alpha apigee archives deploy \
--organization=PROJECT_ID \
--environment=ENV_NAME \
--source=SOURCE_DIR

例如：

gcloud alpha apigee archives deploy \
--organization=my-project \
--environment=prod \
--source=my-dir

您必须使用 --environment 标志指定要在其中部署归档的 Apigee 环境。该 Apigee 环境必须启用归档部署。

如需详细了解如何管理归档部署，请参阅在 Apigee 环境中部署和管理归档。

检查归档部署状态

要检查归档部署状态，请使用 gcloud alpha apigee operations 命令。

以下示例展示了修订版本 ID 为 439fa3f7-6aa4-42ad-8b12-3ca912c75d5c 的操作的归档部署状态是 IN_PROGRESS。

gcloud alpha apigee operations describe b64c2665-b5ac-43cc-9e2d-232e8895c2ed

以下提供了一个响应示例：

Using Apigee organization 'myorg'
Waiting for operation [b64c2665-b5ac-43cc-9e2d-232e8895c2ed] to complete...done.

如需详细了解如何列出归档部署、查看部署详情或删除具有归档部署的环境，请参阅在 Apigee 环境中部署和管理归档。