You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2022/09/21 02:51:06 UTC
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #7952: docs: add tutorials docs and fix others docs
SylviaBABY commented on code in PR #7952:
URL: https://github.com/apache/apisix/pull/7952#discussion_r975980665
##########
docs/en/latest/tutorials/observe-your-api.md:
##########
@@ -101,14 +101,18 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
```
-> To http-logger plugin settings, your can just put your mock server URI address like below:
+:::note
+
+To http-logger plugin settings, your can just put your mock server URI address like below:
Review Comment:
```suggestion
To `http-logger` plugin settings, you can just put your mock server URI address like below:
```
##########
docs/zh/latest/terminology/plugin-config.md:
##########
@@ -106,9 +125,10 @@ $ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f
}
```
-等于
+最后实现的效果：
-```
+```shell
+curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
Review Comment:
```suggestion
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
```
##########
docs/en/latest/tutorials/expose-api.md:
##########
@@ -0,0 +1,124 @@
+---
+id: expose-api
+title: Expose API
+keywords:
+ - API Gateway
+ - Apache APISIX
+ - Expose Service
+description: This article describes how to publish services through the API Gateway Apache APISIX.
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+This article will guide you through APISIX's upstream, routing, and service concepts and introduce how to publish your services through APISIX.
+
+## Concept introduction
+
+### Upstream
+
+[Upstream](../terminology/upstream.md) is a virtual host abstraction that performs load balancing on a given set of service nodes according to the configured rules.
+
+The role of the Upstream is to load balance the service nodes according to the configuration rules, and Upstream information can be directly configured to the Route or Service.
+
+When multiple routes or services refer to the same upstream, you can create an upstream object and use the upstream ID in the Route or Service to reference the upstream to reduce maintenance pressure.
+
+### Route
+
+[Routes](../terminology/route.md) match the client's request based on defined rules, load and execute the corresponding plugins, and forwards the request to the specified Upstream.
+
+### Service
+
+A [Service](../terminology/service.md) is an abstraction of an API (which can also be understood as a set of Route abstractions). It usually corresponds to an upstream service abstraction.
+
+## Prerequisites
+
+Please make sure you have [installed Apache APISIX](../installation-guide.md) before doing the following.
+
+## Expose your service
+
+1. create an Upstream.
Review Comment:
```suggestion
1. Create an Upstream.
```
##########
docs/zh/latest/tutorials/protect-api.md:
##########
@@ -0,0 +1,130 @@
+---
+id: protect-api
+title: 保护 API
+keywords:
+ - API 网关
+ - Apache APISIX
+ - 发布路由
+ - 创建服务
+description: 本文介绍了如何通过 Apache APISIX 发布服务和路由。
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## 描述
+
+本文将为你介绍使用限流限速和安全插件保护你的 API。
+
+## 概念介绍
+
+### 插件
+
+[Plugin](./terminology/plugin.md) 是扩展 APISIX 应用层能力的关键机制，也是在使用 APISIX 时最常用的资源对象，主要是在 HTTP 请求或响应生命周期期间执行的、针对请求的个性化策略。插件可以与路由、服务或消费者绑定。
+
+:::note 注意
+
+如果 [Route](./terminology/route.md)、[Service](./terminology/service.md)、[Plugin Config](./terminology/plugin-config.md) 或 Consumer 都绑定了相同的插件，则只有一份插件配置会生效，插件配置的优先级由高到低顺序是：Consumer > Route > Plugin Config > Service。同时在插件执行过程中也会涉及 6 个阶段，分别是 `rewrite`、`access`、`before_proxy`、`header_filter`、`body_filter` 和 `log`。
+
+:::
+
+## 前提条件
+
+在进行该教程前，请确保你已经[公开服务](./expose-api.md)。
+
+## 保护 API
+
+在很多时候，我们的 API 并不是一个非常安全的，它随时会遭到不正常的访问，一旦访问流量突增，可能就会导致你的 API 发生故障，产生不必要的损失。因此你可以通过速率限制保护你的 API 服务，限制非正常的访问请求，保障 API 服务的稳定运行。我们可以使用手段如下：
+
+1. 限制请求速率；
+2. 限制单位时间内的请求数；
+3. 延迟请求；
+4. 拒绝客户端请求；
+5. 限制响应数据的速率。
+
+为了实现上述功能，APISIX 提供了多个限流限速的插件，包括 [limit-conn](./plugins/limit-conn.md)、[limit-count](./plugins/limit-count.md) 和 [limit-req](./plugins/limit-req.md)。
+
+- `limit-conn` 插件主要用于限制客户端对服务的并发请求数。
+- `limit-req` 插件使用漏桶算法限制对用户服务的请求速率。
+- `limit-count` 插件主要用于在指定的时间范围内，限制每个客户端总请求个数。
+
+接下来，我们将以 `limit-count` 插件为例，为你介绍如何通过限流限速插件保护你的 API：
Review Comment:
```suggestion
接下来，我们将以 `limit-count` 插件为例，为你介绍如何通过限流限速插件保护你的 API。
```
##########
docs/zh/latest/tutorials/observe-your-api.md:
##########
@@ -0,0 +1,245 @@
+---
+title: 监控 API
+keywords:
+ - API 网关
+ - Apache APISIX
+ - 可观测性
+ - 监控
+ - 插件
+description: 本文介绍了 API 网关 Apache APISIX 可观察性插件并了解如何设置这些插件。
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+我们可以利用一些 APISIX 的可观测性插件的强大功能，并了解如何设置这些插件，如何使用它们来理解 API 行为，然后解决影响用户的问题。
Review Comment:
```suggestion
APISIX 中提供了不少具有丰富功能的可观测性插件。你可以通过了解如何使用和设置这些插件，来理解 API 行为，进而对业务的执行更加清晰化。
```
##########
docs/zh/latest/tutorials/protect-api.md:
##########
@@ -0,0 +1,130 @@
+---
+id: protect-api
+title: 保护 API
+keywords:
+ - API 网关
+ - Apache APISIX
+ - 发布路由
+ - 创建服务
+description: 本文介绍了如何通过 Apache APISIX 发布服务和路由。
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## 描述
+
+本文将为你介绍使用限流限速和安全插件保护你的 API。
+
+## 概念介绍
+
+### 插件
+
+[Plugin](./terminology/plugin.md) 是扩展 APISIX 应用层能力的关键机制，也是在使用 APISIX 时最常用的资源对象，主要是在 HTTP 请求或响应生命周期期间执行的、针对请求的个性化策略。插件可以与路由、服务或消费者绑定。
+
+:::note 注意
+
+如果 [Route](./terminology/route.md)、[Service](./terminology/service.md)、[Plugin Config](./terminology/plugin-config.md) 或 Consumer 都绑定了相同的插件，则只有一份插件配置会生效，插件配置的优先级由高到低顺序是：Consumer > Route > Plugin Config > Service。同时在插件执行过程中也会涉及 6 个阶段，分别是 `rewrite`、`access`、`before_proxy`、`header_filter`、`body_filter` 和 `log`。
+
+:::
+
+## 前提条件
+
+在进行该教程前，请确保你已经[公开服务](./expose-api.md)。
+
+## 保护 API
+
+在很多时候，我们的 API 并不是一个非常安全的，它随时会遭到不正常的访问，一旦访问流量突增，可能就会导致你的 API 发生故障，产生不必要的损失。因此你可以通过速率限制保护你的 API 服务，限制非正常的访问请求，保障 API 服务的稳定运行。我们可以使用手段如下：
Review Comment:
```suggestion
在很多时候，我们的 API 并不是处于一个非常安全的状态，它随时会收到不正常的访问，一旦访问流量突增，可能就会导致你的 API 发生故障，产生不必要的损失。因此你可以通过速率限制保护你的 API 服务，限制非正常的访问请求，保障 API 服务的稳定运行。对此，我们可以使用如下方式进行：
```
##########
docs/en/latest/tutorials/protect-api.md:
##########
@@ -0,0 +1,125 @@
+---
+id: protect-api
+title: Protect API
+keywords:
+ - API Gateway
+ - Apache APISIX
+ - Rate Limit
+ - Protect API
+description: This article describes how to secure your API with the rate limiting plugin for API Gateway Apache APISIX.
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+This article describes secure your API with the rate limiting plugin for API Gateway Apache APISIX.
+
+## Concept introduction
+
+### Plugin
+
+This represents the configuration of the plugins that are executed during the HTTP request/response lifecycle. A [Plugin](./terminology/plugin.md) configuration can be bound directly to a Route, a Service, a Consumer or a Plugin Config.
+
+:::note
+
+If [Route](./terminology/route.md), [Service](./terminology/service.md), [Plugin Config](./terminology/plugin-config.md) or Consumer are all bound to the same For plugins, only one plugin configuration will take effect. The priority of plugin configurations is: Consumer > Route > Plugin Config > Service. At the same time, there are 6 stages involved in the plugin execution process, namely `rewrite`, `access`, `before_proxy`, `header_filter`, `body_filter` and `log`.
Review Comment:
```suggestion
If [Route](./terminology/route.md), [Service](./terminology/service.md), [Plugin Config](./terminology/plugin-config.md) or Consumer are all bound to the same for plugins, only one plugin configuration will take effect. The priority of plugin configurations is: Consumer > Route > Plugin Config > Service. At the same time, there are 6 stages involved in the plugin execution process, namely `rewrite`, `access`, `before_proxy`, `header_filter`, `body_filter` and `log`.
```
##########
docs/zh/latest/terminology/plugin-config.md:
##########
@@ -38,9 +49,12 @@ $ curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 -H 'X-API-KEY: edd1c9
}
}
}'
+```
+
+2. 创建路由并绑定 `Plugin Config 1`：
Review Comment:
```suggestion
2. 创建路由并绑定 `Plugin Config 1`。
```
##########
docs/zh/latest/tutorials/expose-api.md:
##########
@@ -0,0 +1,127 @@
+---
+id: expose-api
+title: 发布路由
+keywords:
+ - API 网关
+ - Apache APISIX
+ - 发布路由
+ - 创建服务
+description: 本文介绍了如何通过 Apache APISIX 发布服务和路由。
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## 描述
+
+本文将引导你了解 APISIX 的上游、路由以及服务的概念，并介绍如何通过 APISIX 发布您的服务。
Review Comment:
```suggestion
本文将引导你了解 APISIX 的上游、路由以及服务的概念，并介绍如何通过 APISIX 发布你的服务。
```
##########
docs/zh/latest/terminology/plugin-config.md:
##########
@@ -106,9 +125,10 @@ $ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f
}
```
-等于
+最后实现的效果：
Review Comment:
```suggestion
最后实现的效果如下：
```
##########
docs/zh/latest/terminology/plugin-config.md:
##########
@@ -38,9 +49,12 @@ $ curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 -H 'X-API-KEY: edd1c9
}
}
}'
+```
+
+2. 创建路由并绑定 `Plugin Config 1`：
-# 绑定到路由上
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+```
+curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
Review Comment:
```suggestion
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
```
##########
docs/zh/latest/terminology/plugin-config.md:
##########
@@ -55,14 +69,18 @@ $ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f
如果找不到对应的 Plugin config，该路由上的请求会报 503 错误。
-如果这个路由已经配置了 `plugins`，那么 Plugin config 里面的插件配置会合并进去。
+## 注意事项
+
+如果路由中已经配置了 `plugins`，那么 Plugin Config 里面的插件配置将会与 `plugins` 合并。
+
相同的插件不会覆盖掉 `plugins` 原有的插件。
-举个例子：
+例如：
-```
+```shell
+curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
Review Comment:
```suggestion
curl http://127.0.0.1:9180/apisix/admin/plugin_configs/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
```
##########
docs/zh/latest/tutorials/protect-api.md:
##########
@@ -0,0 +1,130 @@
+---
+id: protect-api
+title: 保护 API
+keywords:
+ - API 网关
+ - Apache APISIX
+ - 发布路由
+ - 创建服务
+description: 本文介绍了如何通过 Apache APISIX 发布服务和路由。
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## 描述
+
+本文将为你介绍使用限流限速和安全插件保护你的 API。
+
+## 概念介绍
+
+### 插件
+
+[Plugin](./terminology/plugin.md) 是扩展 APISIX 应用层能力的关键机制，也是在使用 APISIX 时最常用的资源对象，主要是在 HTTP 请求或响应生命周期期间执行的、针对请求的个性化策略。插件可以与路由、服务或消费者绑定。
+
+:::note 注意
+
+如果 [Route](./terminology/route.md)、[Service](./terminology/service.md)、[Plugin Config](./terminology/plugin-config.md) 或 Consumer 都绑定了相同的插件，则只有一份插件配置会生效，插件配置的优先级由高到低顺序是：Consumer > Route > Plugin Config > Service。同时在插件执行过程中也会涉及 6 个阶段，分别是 `rewrite`、`access`、`before_proxy`、`header_filter`、`body_filter` 和 `log`。
Review Comment:
```suggestion
如果 [路由](./terminology/route.md)、[服务](./terminology/service.md)、[插件配置](./terminology/plugin-config.md) 或消费者都绑定了相同的插件，则只有一份插件配置会生效，插件配置的优先级由高到低顺序是：消费者>路由>插件配置>服务。同时在插件执行过程中也会涉及 6 个阶段，分别是 `rewrite`、`access`、`before_proxy`、`header_filter`、`body_filter` 和 `log`。
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org