Merge pull request #48522 from windsonsea/apicon

[zh] Resync using-api/api-concepts.md

content/zh-cn/docs/reference/using-api/api-concepts.md

@@ -21,7 +21,7 @@ primary resources via the standard HTTP verbs (POST, PUT, PATCH, DELETE,
 GET).
 
 For some resources, the API includes additional subresources that allow
-fine grained authorization (such as separate views for Pod details and
+fine-grained authorization (such as separate views for Pod details and
 log retrievals), and can accept and serve those resources in different
 representations for convenience or efficiency.
 -->
@@ -117,7 +117,7 @@ example: Nodes), and so their names must be unique across the whole cluster.
 ### API verbs
 
 Almost all object resource types support the standard HTTP verbs - GET, POST, PUT, PATCH,
-and DELETE. Kubernetes also uses its own verbs, which are often written lowercase to distinguish
+and DELETE. Kubernetes also uses its own verbs, which are often written in lowercase to distinguish
 them from HTTP verbs.
 
 Kubernetes uses the term **list** to describe returning a [collection](#collections) of
@@ -184,9 +184,12 @@ The following paths are used to retrieve collections and resources:
 
 * Namespace-scoped resources:
 
-  * `GET /apis/GROUP/VERSION/RESOURCETYPE` - return the collection of all instances of the resource type across all namespaces
-  * `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE` - return collection of all instances of the resource type in NAMESPACE
-  * `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME` - return the instance of the resource type with NAME in NAMESPACE
+  * `GET /apis/GROUP/VERSION/RESOURCETYPE` - return the collection of all
+    instances of the resource type across all namespaces
+  * `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE` - return
+    collection of all instances of the resource type in NAMESPACE
+  * `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME` -
+    return the instance of the resource type with NAME in NAMESPACE
 -->
 你还可以访问资源集合（例如：列出所有 Node）。以下路径用于检索集合和资源：
 
@@ -198,8 +201,10 @@ The following paths are used to retrieve collections and resources:
 * 名字空间作用域的资源：
 
   * `GET /apis/GROUP/VERSION/RESOURCETYPE` - 返回所有名字空间中指定资源类型的全部实例的集合
-  * `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE` - 返回名字空间 NAMESPACE 内给定资源类型的全部实例的集合
-  * `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME` - 返回名字空间 NAMESPACE 中给定资源类型的名称为 NAME 的实例
+  * `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE` -
+    返回名字空间 NAMESPACE 内给定资源类型的全部实例的集合
+  * `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME` -
+    返回名字空间 NAMESPACE 中给定资源类型的名称为 NAME 的实例
 
 <!--
 Since a namespace is a cluster-scoped resource type, you can retrieve the list
@@ -334,7 +339,9 @@ Kubernetes API 默认使用 [JSON](https://www.json.org/json-en.html) 来编码
 <!--
 ### YAML resource encoding {#yaml-encoding}
 
-Kubernetes also supports the [`application/yaml`](https://www.rfc-editor.org/rfc/rfc9512.html) media type for both requests and responses. [`YAML`](https://yaml.org/) can be used for defining Kubernetes manifests and API interactions.
+Kubernetes also supports the [`application/yaml`](https://www.rfc-editor.org/rfc/rfc9512.html)
+media type for both requests and responses. [`YAML`](https://yaml.org/)
+can be used for defining Kubernetes manifests and API interactions.
 
 For example:
 -->
@@ -408,7 +415,7 @@ Kubernetes uses an envelope wrapper to encode [Protobuf](https://protobuf.dev/)
 That wrapper starts with a 4 byte magic number to help identify content in disk or in etcd as Protobuf
 (as opposed to JSON). The 4 byte magic number data is followed by a Protobuf encoded wrapper message, which
 describes the encoding and type of the underlying object. Within the Protobuf wrapper message,
-the inner object data is recorded using the `raw` field of Unknown (see the [IDL](##protobuf-encoding-idl)
+the inner object data is recorded using the `raw` field of Unknown (see the [IDL](#protobuf-encoding-idl)
 for more detail).
 -->
 ### Kubernetes Protobuf 编码   {#protobuf-encoding}
@@ -417,7 +424,7 @@ Kubernetes 使用封套形式来对 [Protobuf](https://protobuf.dev/) 响应进
 封套外层由 4 个字节的特殊数字开头，便于从磁盘文件或 etcd 中辩识 Protobuf
 格式的（而不是 JSON）数据。这个 4 字节的特殊数字后跟一个 Protobuf 编码的封套消息，
 此消息描述了下层对象的编码和类型。在 Protobuf 封套消息中，内部对象数据使用 Unknown 的
-`raw` 字段进行记录（有关细节参见 [IDL](##protobuf-encoding-idl)）。
+`raw` 字段进行记录（有关细节参见 [IDL](#protobuf-encoding-idl)）。
 
 <!--
 For example:
@@ -989,7 +996,7 @@ of 500 pods at a time, request those chunks as follows:
    ```
 
 <!--
-2. Continue the previous call, retrieving the next set of 500 pods.
+1. Continue the previous call, retrieving the next set of 500 pods.
 -->
 2. 继续前面的调用，返回下一组 500 个 Pod：
 
@@ -1013,7 +1020,7 @@ of 500 pods at a time, request those chunks as follows:
    ```
 
 <!--
-3. Continue the previous call, retrieving the last 253 pods.
+1. Continue the previous call, retrieving the last 253 pods.
 -->
 3. 继续前面的调用，返回最后 253 个 Pod：
 
@@ -1076,10 +1083,10 @@ collections of different types of resource. Collections have a kind
 named for the resource kind, with `List` appended.
 
 When you query the API for a particular type, all items returned by that query are
-of that type.
-For example, when you **list** Services, the collection response
+of that type. For example, when you **list** Services, the collection response
 has `kind` set to
-[`ServiceList`](/docs/reference/kubernetes-api/service-resources/service-v1/#ServiceList); each item in that collection represents a single Service. For example:
+[`ServiceList`](/docs/reference/kubernetes-api/service-resources/service-v1/#ServiceList);
+each item in that collection represents a single Service. For example:
 -->
 ## 集合 {#collections}
 
@@ -1095,6 +1102,7 @@ has `kind` set to
 ```
 GET /api/v1/services
 ```
+
 ```yaml
 {
   "kind": "ServiceList",
@@ -1447,31 +1455,35 @@ validation are `Ignore`, `Warn` (default), and `Strict`.
 从 1.25 开始，当使用可以提交数据的 HTTP 动词（`POST`、`PUT` 和 `PATCH`）时，
 将通过服务器上的校验检测到对象中无法识别或重复的字段。
 校验的级别可以是 `Ignore`、`Warn`（默认值） 和 `Strict` 之一。
+
 <!--
+`Ignore`
 : The API server succeeds in handling the request as it would without the erroneous fields
-being set, dropping all unknown and duplicate fields and giving no indication it
-has done so.
+  being set, dropping all unknown and duplicate fields and giving no indication it
+  has done so.
 -->
 `Ignore`
 : 使 API 服务器像没有遇到错误字段一样成功处理请求，丢弃所有的未知字段和重复字段，并且不发送丢弃字段的通知。
 
 <!--
+`Warn`
 : (Default) The API server succeeds in handling the request, and reports a
-warning to the client. The warning is sent using the `Warning:` response header,
-adding one warning item for each unknown or duplicate field. For more
-information about warnings and the Kubernetes API, see the blog article
-[Warning: Helpful Warnings Ahead](/blog/2020/09/03/warnings/).
+  warning to the client. The warning is sent using the `Warning:` response header,
+  adding one warning item for each unknown or duplicate field. For more
+  information about warnings and the Kubernetes API, see the blog article
+  [Warning: Helpful Warnings Ahead](/blog/2020/09/03/warnings/).
 -->
 `Warn`
 :（默认值）使 API 服务器成功处理请求，并向客户端发送告警信息。告警信息通过 `Warning:` 响应头发送，
   并为每个未知字段或重复字段添加一条告警信息。有关告警和相关的 Kubernetes API 的信息，
   可参阅博文[告警：增加实用告警功能](/zh-cn/blog/2020/09/03/warnings/)。
 
 <!--
+`Strict`
 : The API server rejects the request with a 400 Bad Request error when it
-detects any unknown or duplicate fields. The response message from the API
-server specifies all the unknown or duplicate fields that the API server has
-detected.
+  detects any unknown or duplicate fields. The response message from the API
+  server specifies all the unknown or duplicate fields that the API server has
+  detected.
 -->
 `Strict`
 : API 服务器检测到任何未知字段或重复字段时，拒绝处理请求并返回 400 Bad Request 错误。
@@ -1646,7 +1658,8 @@ request is made. Some of these fields are:
 
 * `name`: if `generateName` is set, `name` will have a unique random name
 * `creationTimestamp` / `deletionTimestamp`: records the time of creation/deletion
-* `UID`: [uniquely identifies](/docs/concepts/overview/working-with-objects/names/#uids) the object and is randomly generated (non-deterministic)
+* `UID`: [uniquely identifies](/docs/concepts/overview/working-with-objects/names/#uids)
+  the object and is randomly generated (non-deterministic)
 * `resourceVersion`: tracks the persisted version of the object
 * Any field set by a mutating admission controller
 * For the `Service` resource: Ports or IP addresses that the kube-apiserver assigns to Service objects
@@ -1724,7 +1737,8 @@ Kubernetes 使用该 `resourceVersion` 信息，这样 API 服务器可以检测
 <!--
 Instead of sending a PUT request, the client can send an instruction to the API
 server to **patch** an existing resource. A **patch** is typically appropriate
-if the change that the client wants to make isn't conditional on the existing data. Clients that need effective detection of lost updates should consider
+if the change that the client wants to make isn't conditional on the existing data.
+Clients that need effective detection of lost updates should consider
 making their request conditional on the existing `resourceVersion` (either HTTP PUT or HTTP PATCH),
 and then handle any retries that are needed in case there is a conflict.
 
@@ -1908,10 +1922,10 @@ A **patch** update is helpful, because:
 <!--
 However:
 
-* you need more local (client) logic to build the patch; it helps a lot if you have
-  a library implementation of JSON Patch, or even for making a JSON Patch specifically against Kubernetes
-* as the author of client software, you need to be careful when building the patch
-  (the HTTP request body) not to drop fields (the order of operations matters)
+* You need more local (client) logic to build the patch; it helps a lot if you have
+  a library implementation of JSON Patch, or even for making a JSON Patch specifically against Kubernetes.
+* As the author of client software, you need to be careful when building the patch
+  (the HTTP request body) not to drop fields (the order of operations matters).
 -->
 然而：
 
@@ -1932,28 +1946,28 @@ Server-Side Apply has some clear benefits:
 * A single round trip: it rarely requires making a `GET` request first.
   * and you can still detect conflicts for unexpected changes
   * you have the option to force override a conflict, if appropriate
-* Client implementations are easy to make
+* Client implementations are easy to make.
 * You get an atomic create-or-update operation without extra effort
-  (similar to `UPSERT` in some SQL dialects)
+  (similar to `UPSERT` in some SQL dialects).
 -->
 * 仅需一次轮询：通常无需先执行 `GET` 请求。
   * 并且你仍然可以检测到意外更改造成的冲突
   * 合适的时候，你可以选择强制覆盖冲突
-* 客户端实现简单
+* 客户端实现简单。
 * 你可以轻松获得原子级别的 create 或 update 操作，无需额外工作
-  （类似于某些 SQL 语句中的 `UPSERT`）
+  （类似于某些 SQL 语句中的 `UPSERT`）。
 
 <!--
 However:
 
-* Server-Side Apply does not work at all for field changes that depend on a current value of the object
+* Server-Side Apply does not work at all for field changes that depend on a current value of the object.
 * You can only apply updates to objects. Some resources in the Kubernetes HTTP API are
   not objects (they do not have a `.metadata` field), and Server-Side Apply
   is only relevant for Kubernetes objects.
 -->
 然而：
 
-* 服务器端应用不适合依赖对象当前值的字段更改
+* 服务器端应用不适合依赖对象当前值的字段更改。
 * 你只能更新对象。Kubernetes HTTP API 中的某些资源不是对象（它们没有 `.metadata` 字段），
   并且服务器端应用只能用于 Kubernetes 对象。
 
@@ -1986,9 +2000,12 @@ API 客户端只能比较两个资源版本的相等性（这意味着你不能
 Clients find resource versions in resources, including the resources from the response
 stream for a **watch**, or when using **list** to enumerate resources.
 
-[v1.meta/ObjectMeta](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#objectmeta-v1-meta) - The `metadata.resourceVersion` of a resource instance identifies the resource version the instance was last modified at.
+[v1.meta/ObjectMeta](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#objectmeta-v1-meta) -
+The `metadata.resourceVersion` of a resource instance identifies the resource version the instance was last modified at.
 
-[v1.meta/ListMeta](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#listmeta-v1-meta) - The `metadata.resourceVersion` of a resource collection (the response to a **list**) identifies the resource version at which the collection was constructed.
+[v1.meta/ListMeta](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#listmeta-v1-meta) -
+The `metadata.resourceVersion` of a resource collection (the response to a **list**) identifies the
+resource version at which the collection was constructed.
 -->
 ### metadata 中的 `resourceVersion`  {#resourceVersion-in-metadata}
 
@@ -2080,30 +2097,29 @@ This table explains the behavior of **list** requests with various combinations
 下表解释了具有各种 `resourceVersion` 和 `resourceVersionMatch` 组合的 **list** 请求的行为：
 
 <!--
-| resourceVersionMatch param            | paging params                 | resourceVersion not set | resourceVersion="0"                       | resourceVersion="{value other than 0}" |
-|---------------------------------------|-------------------------------|-----------------------|-------------------------------------------|----------------------------------------|
-| _unset_            | _limit unset_                   | Most Recent           | Any                                       | Not older than                         |
-| _unset_            | limit=\<n\>, _continue unset_     | Most Recent           | Any                                       | Exact                                  |
-| _unset_            | limit=\<n\>, continue=\<token\> | Continue Token, Exact | Invalid, treated as Continue Token, Exact | Invalid, HTTP `400 Bad Request`        |
-| `resourceVersionMatch=Exact`        | _limit unset_                 | Invalid               | Invalid                                   | Exact                                  |
-| `resourceVersionMatch=Exact`        | limit=\<n\>, _continue unset_ | Invalid               | Invalid                                   | Exact                                  |
-| `resourceVersionMatch=NotOlderThan` | _limit unset_                 | Invalid               | Any                                       | Not older than                         |
-| `resourceVersionMatch=NotOlderThan` | limit=\<n\>, _continue unset_ | Invalid               | Any                                       | Not older than                         |
+| resourceVersionMatch param | paging params | resourceVersion not set | resourceVersion="0" | resourceVersion="{value other than 0}" |
+|----------------------------|---------------|-------------------------|---------------------|----------------------------------------|
+| _unset_ | _limit unset_ | Most Recent | Any | Not older than |
+| _unset_ | limit=\<n\>, _continue unset_ | Most Recent | Any | Exact |
+| _unset_ | limit=\<n\>, continue=\<token\>| Continue Token, Exact | Invalid, treated as Continue Token, Exact | Invalid, HTTP `400 Bad Request` |
+| `resourceVersionMatch=Exact` | _limit unset_ | Invalid | Invalid | Exact |
+| `resourceVersionMatch=Exact` | limit=\<n\>, _continue unset_ | Invalid | Invalid | Exact |
+| `resourceVersionMatch=NotOlderThan` | _limit unset_ | Invalid | Any | Not older than |
+| `resourceVersionMatch=NotOlderThan` | limit=\<n\>, _continue unset_ | Invalid | Any | Not older than |
 
 {{</* /table */>}}
 -->
-
 {{< table caption="list 操作的 resourceVersionMatch 与分页参数" >}}
 
-| resourceVersionMatch 参数               | 分页参数                        | resourceVersion 未设置  | resourceVersion="0"                     | resourceVersion="\<非零值\>"     |
-|-----------------------------------------|---------------------------------|-------------------------|-----------------------------------------|----------------------------------|
-| **未设置**            | **limit 未设置**                      | 最新版本                | 任意版本                                | 不老于指定版本                   |
-| **未设置**            | limit=\<n\>, **continue 未设置**        | 最新版本                | 任意版本                                | 精确匹配                         |
-| **未设置**           | limit=\<n\>, continue=\<token\>     | 从 token 开始、精确匹配 | 非法请求，视为从 token 开始、精确匹配  | 非法请求，返回 HTTP `400 Bad Request` |
-| `resourceVersionMatch=Exact` [1]         | **limit 未设置**                      | 非法请求                | 非法请求                                | 精确匹配                         |
-| `resourceVersionMatch=Exact` [1]         | limit=\<n\>, **continue 未设置**        | 非法请求                | 非法请求                                | 精确匹配                         |
-| `resourceVersionMatch=NotOlderThan` [1]  | **limit 未设置**             | 非法请求                | 任意版本                                | 不老于指定版本                   |
-| `resourceVersionMatch=NotOlderThan` [1]  | limit=\<n\>, **continue 未设置** | 非法请求                | 任意版本                                | 不老于指定版本                   |
+| resourceVersionMatch 参数 | 分页参数 | resourceVersion 未设置 | resourceVersion="0" | resourceVersion="\<非零值\>" |
+|--------------------------|---------|-----------------------|---------------------|-----------------------------|
+| **未设置** | **limit 未设置** | 最新版本 | 任意版本 | 不老于指定版本 |
+| **未设置** | limit=\<n\>, **continue 未设置** | 最新版本 | 任意版本 | 精确匹配 |
+| **未设置** | limit=\<n\>, continue=\<token\> | 从 token 开始、精确匹配 | 非法请求，视为从 token 开始、精确匹配 | 非法请求，返回 HTTP `400 Bad Request` |
+| `resourceVersionMatch=Exact` [1] | **limit 未设置** | 非法请求 | 非法请求 | 精确匹配 |
+| `resourceVersionMatch=Exact` [1] | limit=\<n\>, **continue 未设置** | 非法请求 | 非法请求 | 精确匹配 |
+| `resourceVersionMatch=NotOlderThan` [1] | **limit 未设置** | 非法请求 | 任意版本 | 不老于指定版本 |
+| `resourceVersionMatch=NotOlderThan` [1] | limit=\<n\>, **continue 未设置** | 非法请求 | 任意版本 | 不老于指定版本 |
 
 {{< /table >}}