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/20 12:10:35 UTC

[GitHub] [apisix] hf400159 opened a new pull request, #7952: docs: add tutorials docs and fix others docs

hf400159 opened a new pull request, #7952:
URL: https://github.com/apache/apisix/pull/7952

   ### Description
   
   <!-- Please include a summary of the change and which issue is fixed. -->
   <!-- Please also include relevant motivation and context. -->
   
   Fixes # (issue)
   
   ### Checklist
   
   - [ ] I have explained the need for this PR and the problem it solves
   - [ ] I have explained the changes or the new features added to this PR
   - [ ] I have added tests corresponding to this change
   - [ ] I have updated the documentation to reflect this change
   - [ ] I have verified that this change is backward compatible (If not, please discuss on the [APISIX mailing list](https://github.com/apache/apisix/tree/master#community) first)
   
   <!--
   
   Note
   
   1. Mark the PR as draft until it's ready to be reviewed.
   2. Always add/update tests for any changes unless you have a good reason.
   3. Always update the documentation to reflect the changes made in the PR.
   4. Make a new commit to resolve conversations instead of `push -f`.
   5. To resolve merge conflicts, merge master instead of rebasing.
   6. Use "request review" to notify the reviewer after making changes.
   7. Only a reviewer can mark a conversation as resolved.
   
   -->
   


-- 
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

[GitHub] [apisix] juzhiyuan commented on a diff in pull request #7952: docs: add tutorials docs and fix others docs

Posted by "juzhiyuan (via GitHub)" <gi...@apache.org>.
juzhiyuan commented on code in PR #7952:
URL: https://github.com/apache/apisix/pull/7952#discussion_r1150118718


##########
docs/en/latest/tutorials/expose-api.md:
##########
@@ -0,0 +1,123 @@
+---
+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.
+
+Create an Upstream service containing `httpbin.org` that you can use for testing. This is a return service that will return the parameters we passed in the request.
+
+```
+curl "http://127.0.0.1:9180/apisix/admin/upstreams/1" \
+-H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
+{
+  "type": "roundrobin",
+  "nodes": {
+    "httpbin.org:80": 1
+  }
+}'
+```
+
+In this command, we specify the Admin API Key of Apache APISIX as `edd1c9f034335f136f87ad84b625c8f1`, use `roundrobin` as the load balancing mechanism, and set `httpbin.org:80` as the upstream service. To bind this upstream to a route, `upstream_id` needs to be set to `1` here. Here you can specify multiple upstreams under `nodes` to achieve load balancing.
+
+For more information, please refer to [Upstream](../terminology/upstream.md).
+
+2. Create a Route.
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes/1" \
+-H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
+{
+  "methods": ["GET"],
+  "host": "example.com",
+  "uri": "/anything/*",
+  "upstream_id": "1"
+}'
+```
+
+:::note
+
+Adding an `upstream` object to your route can achieve the above effect.
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes/1" \
+-H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
+{
+  "methods": ["GET"],
+  "host": "example.com",
+  "uri": "/anything/*",
+  "upstream": {
+    "type": "roundrobin",
+    "nodes": {
+      "httpbin.org:80": 1
+    }
+  }
+}'
+```
+
+:::
+
+3. Test
+
+After creating the Route, you can test the Service with the following command:
+
+```
+curl -i -X GET "http://127.0.0.1:9080/get?foo1=bar1&foo2=bar2" -H "Host: httpbin.org"

Review Comment:
   cc @guitu168 



-- 
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

[GitHub] [apisix] SylviaBABY commented on a diff in pull request #7952: docs: add tutorials docs and fix others docs

Posted by GitBox <gi...@apache.org>.
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

[GitHub] [apisix] spacewander merged pull request #7952: docs: add tutorials docs and fix others docs

Posted by GitBox <gi...@apache.org>.
spacewander merged PR #7952:
URL: https://github.com/apache/apisix/pull/7952


-- 
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

[GitHub] [apisix] SylviaBABY commented on a diff in pull request #7952: docs: add tutorials docs and fix others docs

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #7952:
URL: https://github.com/apache/apisix/pull/7952#discussion_r975986811


##########
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:
   Because the relevant definitions have been explained in the previous article, I think it can be displayed in Chinese here.



-- 
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

[GitHub] [apisix] SylviaBABY commented on a diff in pull request #7952: docs: add tutorials docs and fix others docs

Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #7952:
URL: https://github.com/apache/apisix/pull/7952#discussion_r976005753


##########
docs/zh/latest/tutorials/observe-your-api.md:
##########
@@ -0,0 +1,236 @@
+---
+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 行为，进而使整个业务流程更加清晰。
+
+## API 可观测性
+
+**API 可观测性**已经成为 API 开发的一部分，因为它解决了与 API 一致性、可靠性和快速迭代 API 功能的相关问题。可观测性可分为三个关键部分：日志、指标、链路追踪，接下来让我们逐个了解它们。
+
+![Observability of three key areas](https://static.apiseven.com/2022/09/14/6321cf14c555a.jpg)
+
+## 前提条件
+
+在进行该教程之前，请确保你已经[公开服务](./expose-api.md)。
+
+## 日志
+
+在 APISIX 中，**日志**可分为访问日志和错误日志。访问日志主要记录了每个请求的上下文信息，错误日志则是 APISIX 运行打印的日志信息，包括 NGINX 和插件相关的信息。APISIX 的日志存储在 `./apisix/logs/` 目录下。当然你可以通过一些 APISIX 的日志插件，将 APISIX 的日志发送到指定的日志服务中，APISIX 提供了以下插件：
+
+- [http-logger](../plugins/http-logger.md)
+- [skywalking-logger](../plugins/skywalking-logger.md)
+- [tcp-logger](../plugins/tcp-logger.md)
+- [kafka-logger](../plugins/kafka-logger.md)
+- [rocketmq-logger](../plugins/rocketmq-logger.md)
+- [udp-logger](../plugins/udp-logger.md)
+- [clickhouse-logger](../plugins/clickhouse-logger.md)
+- [error-logger](../plugins/error-log-logger.md)
+- [google-cloud-logging](../plugins/google-cloud-logging.md)
+
+你可以在 APISIX [插件中心](../plugins/http-logger.md) 查看 APISIX 支持的所有日志插件。接下来我们将使用 `http-logger` 插件为你演示如何将 APISIX 的日志数据发送到 HTPP/HTTPS 服务器中。
+
+:::note 注意
+
+你可以使用 [mockbin.com](https://mockbin.org/) 生成一个模拟的 HTTP 服务器来存储和查看日志。
+
+:::
+
+以下示例展示了在指定路由上启动 `http-logger` 的示例。
+
+```shell
+
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+  "plugins": {
+    "http-logger": {
+      "uri": "http://mockbin.org/bin/5451b7cd-af27-41b8-8df1-282ffea13a61"
+    }
+  },
+  "upstream_id": "1",
+  "uri": "/get"
+}'
+
+```
+
+:::note 注意
+
+你可以通过修改 `uri` 属性，将上述 `http-logger` 的服务器地址更换为你的服务器地址：
+
+```json
+{
+   "uri": "http://mockbin.org/bin/5451b7cd-af27-41b8-8df1-282ffea13a61"
+}
+```
+
+:::
+
+创建成功后，你可以通过以下命令向 `get` 端点发送请求以生成日志。
+
+```shell
+curl -i http://127.0.0.1:9080/get
+```
+
+请求成功后，你可以单击[模拟服务器链接](http://mockbin.org/bin/5451b7cd-af27-41b8-8df1-282ffea13a61/log)查看访问日志。
+
+![http-logger-plugin-test-screenshot](https://static.apiseven.com/2022/09/14/6321d1d83eb7a.png)
+
+## 指标
+
+**指标**是在⼀段时间内测量的数值。与⽇志不同，指标在默认情况下是结构化的，这使得查询和优化存储变得更加容易。而 APISIX 也提供了 [Prometheus](../plugins/prometheus.md) 的插件来获取你的 API 指标，并在 Prometheus 中暴露它们。通过使用 APISIX 提供的 Grafana 仪表板元数据，并从 Prometheus 中获取指标，更加方便的监控你的 API。
+
+你可以通过以下命令启用 `prometheus` 插件：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1  \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+  "uri": "/get",
+  "plugins": {
+    "prometheus": {}
+  },
+  "upstream_id": "1"
+}'
+```
+
+启用成功后，你可以通过 `/apisix/prometheus/metrics` 接口获取 APISIX 的指标。
+
+```shell
+curl -i http://127.0.0.1:9091/apisix/prometheus/metrics
+```
+
+返回结果如下：
+
+```text
+HTTP/1.1 200 OK
+Server: openresty
+Content-Type: text/plain; charset=utf-8
+Transfer-Encoding: chunked
+Connection: keep-alive
+
+# HELP apisix_batch_process_entries batch process remaining entries
+# TYPE apisix_batch_process_entries gauge
+apisix_batch_process_entries{name="http logger",route_id="1",server_addr="172.19.0.8"} 0
+# HELP apisix_etcd_modify_indexes Etcd modify index for APISIX keys
+# TYPE apisix_etcd_modify_indexes gauge
+apisix_etcd_modify_indexes{key="consumers"} 17819
+apisix_etcd_modify_indexes{key="global_rules"} 17832
+apisix_etcd_modify_indexes{key="max_modify_index"} 20028
+apisix_etcd_modify_indexes{key="prev_index"} 18963
+apisix_etcd_modify_indexes{key="protos"} 0
+apisix_etcd_modify_indexes{key="routes"} 20028
+...
+```
+
+你还可以通过 `http://localhost:9090/targets` 在 Prometheus 仪表板上查看端点的状态。
+
+![plu​​gin-orchestration-configure-rule-screenshot](https://static.apiseven.com/2022/09/14/6321d30b32024.png)
+
+如上图，APISIX 公开的指标端点已启动并正在运行。
+
+现在，你可以查询 `apisix_http_status` 的指标，查看 APISIX 处理了哪些 HTTP 请求及其结果。
+
+![prometheus-plugin-dashboard-query-http-status-screenshot](https://static.apiseven.com/2022/09/14/6321d30aed3b2.png)
+
+除此之外，你还可以查看在本地实例中运行的 Grafana 仪表板。请访问 `http://localhost:3000/`。
+
+![prometheus-plugin-grafana-dashboard-screenshot](https://static.apiseven.com/2022/09/14/6321d30bba97c.png)
+
+APISIX 还提供了其他两个插件：

Review Comment:
   ```suggestion
   目前，APISIX 还提供了其他两个日志相关插件：
   ```



##########
docs/zh/latest/tutorials/observe-your-api.md:
##########
@@ -0,0 +1,236 @@
+---
+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 行为，进而使整个业务流程更加清晰。
+
+## API 可观测性
+
+**API 可观测性**已经成为 API 开发的一部分，因为它解决了与 API 一致性、可靠性和快速迭代 API 功能的相关问题。可观测性可分为三个关键部分：日志、指标、链路追踪，接下来让我们逐个了解它们。
+
+![Observability of three key areas](https://static.apiseven.com/2022/09/14/6321cf14c555a.jpg)
+
+## 前提条件
+
+在进行该教程之前，请确保你已经[公开服务](./expose-api.md)。
+
+## 日志
+
+在 APISIX 中，**日志**可分为访问日志和错误日志。访问日志主要记录了每个请求的上下文信息，错误日志则是 APISIX 运行打印的日志信息，包括 NGINX 和插件相关的信息。APISIX 的日志存储在 `./apisix/logs/` 目录下。当然你可以通过一些 APISIX 的日志插件，将 APISIX 的日志发送到指定的日志服务中，APISIX 提供了以下插件：
+
+- [http-logger](../plugins/http-logger.md)
+- [skywalking-logger](../plugins/skywalking-logger.md)
+- [tcp-logger](../plugins/tcp-logger.md)
+- [kafka-logger](../plugins/kafka-logger.md)
+- [rocketmq-logger](../plugins/rocketmq-logger.md)
+- [udp-logger](../plugins/udp-logger.md)
+- [clickhouse-logger](../plugins/clickhouse-logger.md)
+- [error-logger](../plugins/error-log-logger.md)
+- [google-cloud-logging](../plugins/google-cloud-logging.md)
+
+你可以在 APISIX [插件中心](../plugins/http-logger.md) 查看 APISIX 支持的所有日志插件。接下来我们将使用 `http-logger` 插件为你演示如何将 APISIX 的日志数据发送到 HTPP/HTTPS 服务器中。
+
+:::note 注意
+
+你可以使用 [mockbin.com](https://mockbin.org/) 生成一个模拟的 HTTP 服务器来存储和查看日志。
+
+:::
+
+以下示例展示了在指定路由上启动 `http-logger` 的示例。
+
+```shell
+
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+  "plugins": {
+    "http-logger": {
+      "uri": "http://mockbin.org/bin/5451b7cd-af27-41b8-8df1-282ffea13a61"
+    }
+  },
+  "upstream_id": "1",
+  "uri": "/get"
+}'
+
+```
+
+:::note 注意
+
+你可以通过修改 `uri` 属性，将上述 `http-logger` 的服务器地址更换为你的服务器地址：
+
+```json
+{
+   "uri": "http://mockbin.org/bin/5451b7cd-af27-41b8-8df1-282ffea13a61"
+}
+```
+
+:::
+
+创建成功后，你可以通过以下命令向 `get` 端点发送请求以生成日志。
+
+```shell
+curl -i http://127.0.0.1:9080/get
+```
+
+请求成功后，你可以单击[模拟服务器链接](http://mockbin.org/bin/5451b7cd-af27-41b8-8df1-282ffea13a61/log)查看访问日志。
+
+![http-logger-plugin-test-screenshot](https://static.apiseven.com/2022/09/14/6321d1d83eb7a.png)
+
+## 指标
+
+**指标**是在⼀段时间内测量的数值。与⽇志不同，指标在默认情况下是结构化的，这使得查询和优化存储变得更加容易。而 APISIX 也提供了 [Prometheus](../plugins/prometheus.md) 的插件来获取你的 API 指标，并在 Prometheus 中暴露它们。通过使用 APISIX 提供的 Grafana 仪表板元数据，并从 Prometheus 中获取指标，更加方便的监控你的 API。

Review Comment:
   ```suggestion
   **指标**是在⼀段时间内测量的数值。与⽇志不同，指标在默认情况下是结构化的，这使得查询和优化存储变得更加容易。而 APISIX 也提供了 [Prometheus](../plugins/prometheus.md) 的插件来获取你的 API 指标，并在 Prometheus 中暴露它们。通过使用 APISIX 提供的 Grafana 仪表板元数据，并从 Prometheus 中获取指标，更加方便地监控你的 API。
   ```



-- 
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

[GitHub] [apisix] juzhiyuan commented on a diff in pull request #7952: docs: add tutorials docs and fix others docs

Posted by "juzhiyuan (via GitHub)" <gi...@apache.org>.
juzhiyuan commented on code in PR #7952:
URL: https://github.com/apache/apisix/pull/7952#discussion_r1150118134


##########
docs/en/latest/tutorials/expose-api.md:
##########
@@ -0,0 +1,123 @@
+---
+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.
+
+Create an Upstream service containing `httpbin.org` that you can use for testing. This is a return service that will return the parameters we passed in the request.
+
+```
+curl "http://127.0.0.1:9180/apisix/admin/upstreams/1" \
+-H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
+{
+  "type": "roundrobin",
+  "nodes": {
+    "httpbin.org:80": 1
+  }
+}'
+```
+
+In this command, we specify the Admin API Key of Apache APISIX as `edd1c9f034335f136f87ad84b625c8f1`, use `roundrobin` as the load balancing mechanism, and set `httpbin.org:80` as the upstream service. To bind this upstream to a route, `upstream_id` needs to be set to `1` here. Here you can specify multiple upstreams under `nodes` to achieve load balancing.
+
+For more information, please refer to [Upstream](../terminology/upstream.md).
+
+2. Create a Route.
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes/1" \
+-H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
+{
+  "methods": ["GET"],
+  "host": "example.com",
+  "uri": "/anything/*",
+  "upstream_id": "1"
+}'
+```
+
+:::note
+
+Adding an `upstream` object to your route can achieve the above effect.
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes/1" \
+-H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" -X PUT -d '
+{
+  "methods": ["GET"],
+  "host": "example.com",
+  "uri": "/anything/*",
+  "upstream": {
+    "type": "roundrobin",
+    "nodes": {
+      "httpbin.org:80": 1
+    }
+  }
+}'
+```
+
+:::
+
+3. Test
+
+After creating the Route, you can test the Service with the following command:
+
+```
+curl -i -X GET "http://127.0.0.1:9080/get?foo1=bar1&foo2=bar2" -H "Host: httpbin.org"

Review Comment:
   It should be `/anything` and `example.com` here.



-- 
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