From 8bfb2f431803b5e1727c8f3ac1df81b7228d421d Mon Sep 17 00:00:00 2001 From: JieDing Date: Sat, 6 Nov 2021 20:17:35 +0800 Subject: [PATCH 01/60] Update README.md CloudEvents Chinese manual aims to provide a fast and brief introduction of CloudEvents in Chinese for people who are new to CloudEvents. --- README.md | 148 +++++++++++++++++++++++++----------------------------- 1 file changed, 69 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index c26f0b7df..5396058f1 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,37 @@ -# CloudEvents +# CloudEvents Chinese Manual ![CloudEvents logo](https://github.com/cncf/artwork/blob/master/projects/cloudevents/horizontal/color/cloudevents-horizontal-color.png) -Events are everywhere. However, event producers tend to describe events -differently. +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. -The lack of a common way of describing events means developers must constantly -re-learn how to consume events. This also limits the potential for libraries, -tooling and infrastructure to aide the delivery of event data across -environments, like SDKs, event routers or tracing systems. The portability and -productivity we can achieve from event data is hindered overall. +声明：这份中文手册旨在帮助初次接触CloudEvents的人快速建立起CloudEvents的相关认知。 +手册中的大部分内容翻译自英文版的CloudEvents标准，当你遇到令你困惑的内容时，请对照英文版理解。 -CloudEvents is a specification for describing event data in common formats to -provide interoperability across services, platforms and systems. +事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 -CloudEvents has received a large amount of industry interest, ranging from major -cloud providers to popular SaaS companies. CloudEvents is hosted by the -[Cloud Native Computing Foundation](https://cncf.io) (CNCF) and was approved as -a Cloud Native sandbox level project on -[May 15, 2018](https://docs.google.com/presentation/d/1KNSv70fyTfSqUerCnccV7eEC_ynhLsm9A_kjnlmU_t0/edit#slide=id.g37acf52904_1_41). +对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。它同样限制了那些用来帮助事件数据完成 +跨环境传输的库(如SDKs)，工具(如事件路由器)和基础设施(如事件追踪系统)的发展。总体来看，这种匮乏严重阻碍了事件数据的 +可移植性和生产力。 -## CloudEvents Documents +CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 -The following documents are available: +CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvents被[云原生计算基金会](https://cncf.io) (CNCF)持有， +在[2018/05/15](https://docs.google.com/presentation/d/1KNSv70fyTfSqUerCnccV7eEC_ynhLsm9A_kjnlmU_t0/edit#slide=id.g37acf52904_1_41) +被选为云原生沙盒级项目。 -| | Latest Release | Working Draft | +## CloudEvents 文件 + +现有文件如下: + +| | 最新版本 | 工作草稿 | | :---------------------------- | :----------------------------------------------------------------------------: | :---------------------------------------------------------------------------------: | -| **Core Specification:** | +| **核心标准:** | | CloudEvents | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/spec.md) | [master](https://github.com/cloudevents/spec/blob/master/spec.md) | | | -| **Optional Specifications:** | +| **可选标准:** | | AMQP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/amqp-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-protocol-binding.md) | | AVRO Event Format | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/avro-format.md) | [master](https://github.com/cloudevents/spec/blob/master/avro-format.md) | | HTTP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/http-protocol-binding.md) | @@ -39,26 +41,22 @@ The following documents are available: | NATS Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/nats-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/nats-protocol-binding.md) | | Web hook | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md) | [master](https://github.com/cloudevents/spec/blob/master/http-webhook.md) | | | -| **Additional Documentation:** | +| **附加文件:** | | CloudEvents Adapters | - | [master](https://github.com/cloudevents/spec/blob/master/adapters.md) | | CloudEvents SDK Requirements | - | [master](https://github.com/cloudevents/spec/blob/master/SDK.md) | | Documented Extensions | - | [master](https://github.com/cloudevents/spec/blob/master/documented-extensions.md) | | Primer | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/primer.md) | [master](https://github.com/cloudevents/spec/blob/master/primer.md) | | Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | -If you are new to CloudEvents, it is recommended that you start by reading the -[Primer](primer.md) for an overview of the specification's goals and design -decisions, and then move on to the [core specification](spec.md). +对于初次接触CloudEvents的同学，建议通过阅读[入门文档](primer.md)增加对CloudEvents规范的目标和设计理念 +的总体理解，然后再继续阅读[核心规范](spec.md)。 -Since not all event producers generate CloudEvents by default, there is -documentation describing the recommended process for adapting some popular -events into CloudEvents, see -[CloudEvents Adapters](https://github.com/cloudevents/spec/blob/master/adapters.md). +由于并非所有事件生产者都默认生产符合CloudEvents规范的事件，因此可以用[CloudEvents适配器](https://github.com/cloudevents/spec/blob/master/adapters.md) +来将现有的事件与CloudEvents做适配。 ## SDKs -In addition to the documentation mentioned above, there are also an -[SDK proposal](SDK.md) and a set of SDKs being developed: +除了上述文档，我们还提供了[SDK 提议](SDK.md)以及一些编程语言的SDK： - [CSharp](https://github.com/cloudevents/sdk-csharp) - [Go](https://github.com/cloudevents/sdk-go) @@ -66,79 +64,71 @@ In addition to the documentation mentioned above, there are also an - [Javascript](https://github.com/cloudevents/sdk-javascript) - [Python](https://github.com/cloudevents/sdk-python) -## Community - -Learn more about the people and organizations who are creating a dynamic cloud -native ecosystem by making our systems interoperable with CloudEvents. - -- [Contributors](community/contributors.md): people and organizations who helped - us get started or are actively working on the CloudEvents specification. -- Coming soon: [demos & open source](community/README.md) -- if you have - something to share about your use of CloudEvents, please submit a PR! +## 社区 -## Process +在社区里，你可以了解到更多致力于搭建一个动态、云原生的生态系统的成员和组织。 +他们不断尝试提升现有系统和CloudEvents间的互操作性和兼容性。 -The CloudEvents project is working to formalize the [specification](spec.md) -based on [design goals](primer.md#design-goals) which focus on interoperability -between systems which generate and respond to events. +- [贡献者](community/contributors.md): + 是指那些帮助我们制定规范或是积极活跃在CloudEvents规范相关工作的成员和组织。 +- 即将推出: [demos & open source](community/README.md) -- + 如果你希望向我们分享关于你对CloudEvents的使用，请通过提交PR让我们看到。 -In order to achieve these goals, the project must describe: +## 步骤 -- Common attributes of an _event_ that facilitate interoperability -- One or more common architectures that are in active use today or planned to be - built by its members -- How events are transported from producer to consumer via at least one protocol -- Identify and resolve whatever else is needed for interoperability +CloudEvents项目 [旨在](primer.md#design-goals)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 +的[标准](spec.md)。 -## Communications +为了完成这个目标，这个项目必须描述： -The mailing list for e-mail communications: +- 一系列能够提升互操作性的用来描述事件的属性 +- 一个或多个通用架构，这些架构必须是当下活跃的或是正在计划被完成的 +- 事件是如何在一种或多种协议下从生产者传输到消费者的 +- 识别并解决任何能提升互操作性的问题 +## 联系方式 -- Send emails to: [cncf-cloudevents](mailto:cncf-cloudevents@lists.cncf.io) -- To subscribe see: https://lists.cncf.io/g/cncf-cloudevents -- Archives are at: https://lists.cncf.io/g/cncf-cloudevents/topics +邮件联系方式如下: -And a #cloudevents Slack channel under -[CNCF's Slack workspace](https://slack.cncf.io/). +- 发送EMail至: [cncf-cloudevents](mailto:cncf-cloudevents@lists.cncf.io) +- 订阅地址: https://lists.cncf.io/g/cncf-cloudevents +- 存档地址: https://lists.cncf.io/g/cncf-cloudevents/topics -## Meeting Time +## 会议时间 -See the [CNCF public events calendar](https://www.cncf.io/community/calendar/). -This specification is being developed by the -[CNCF Serverless Working Group](https://github.com/cncf/wg-serverless). This -working group meets every Thursday at 9AM PT (USA Pacific): +会议日期请查看 [CNCF 公开活动日历](https://www.cncf.io/community/calendar/). +CloudEvents规范由 +[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless)开发完成。 +这个工作组每周四的上午9点(美国-太平洋时间)通过Zoom开展视频会议。 +通过 PC, Mac, Linux, iOS or Android来参加活动: https://zoom.us/my/cncfserverlesswg -Join from PC, Mac, Linux, iOS or Android: https://zoom.us/my/cncfserverlesswg - -Or iPhone one-tap : +或者通过 iPhone one-tap : US: +16465588656,,3361029682# or +16699006833,,3361029682# -Or Telephone: +或者电话接入: Dial: US: +1 646 558 8656 (US Toll) or +1 669 900 6833 (US Toll) or +1 855 880 1246 (Toll Free) or +1 877 369 0926 (Toll Free) -Meeting ID: 336 102 9682 +会议 ID: 336 102 9682 -International numbers available: +国际号码接入: https://zoom.us/zoomconference?m=QpOqQYfTzY_Gbj9_8jPtsplp1pnVUKDr -NOTE: Please use \*6 to mute/un-mute your phone during the call. - -World Time Zone Converter: +世界时区转化器: http://www.thetimezoneconverter.com/?t=9:00%20am&tz=San%20Francisco& -## Meeting Minutes +## 会议记录 + +历史会议记录在 +[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) +查看。 -The minutes from our calls are available -[here](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#). +历史会议录像在 +[这里](https://www.youtube.com/playlist?list=PLj6h78yzYM2Ph7YoBIgsZNW_RGJvNlFOt) +查看。 -Recording from our calls are available -[here](https://www.youtube.com/playlist?list=PLj6h78yzYM2Ph7YoBIgsZNW_RGJvNlFOt). +工作组会定期举办与主流会议一致的线下会议。查看[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) +了解更多未来计划。 -Periodically, the group may have in-person meetings that coincide with a major -conference. Please see the -[meeting minutes](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) -for any future plans. From 86b7128ba48e25997f1d26785468cd58b0e95bf1 Mon Sep 17 00:00:00 2001 From: JieDing Date: Sat, 6 Nov 2021 21:16:45 +0800 Subject: [PATCH 02/60] Update primer.md --- primer.md | 49 +++++++++++++++++++++++-------------------------- 1 file changed, 23 insertions(+), 26 deletions(-) diff --git a/primer.md b/primer.md index 367262195..5556eb330 100644 --- a/primer.md +++ b/primer.md @@ -1,35 +1,32 @@ -# CloudEvents Primer - Version 1.0 - -## Abstract - -This non-normative document provides an overview of the CloudEvents -specification. It is meant to complement the CloudEvent specification to provide -additional background and insight into the history and design decisions made -during the development of the specification. This allows the specification -itself to focus on the normative technical details. - -## Table of Contents - -- [History](#history) -- [CloudEvents Concepts](#cloudevents-concepts) -- [Design Goals](#design-goals) -- [Architecture](#architecture) -- [Versioning of Attributes](#versioning-of-attributes) -- [CloudEvent Attributes](#cloudevent-attributes) -- [CloudEvent Attribute Extensions](#cloudevent-attribute-extensions) -- [Creating CloudEvents](#creating-cloudevents) -- [Qualifying Protocols and Encodings](#qualifying-protocols-and-encodings) -- [Proprietary Protocols and Encodings](#proprietary-protocols-and-encodings) +# CloudEvents 入门文档 - 1.0 版本 + +## 摘要 + +这份非技术规范文档用来为你提供关于CloudEvents规范的总体概览。它补充了CloudEvents规范的相关背景以及在制定 +本规范时的历史和设计理念。这样，CloudEvents规范就只需要关注Events规范的技术细节，而不用过多地关心 +背景相关内容。 + +## 目录 + +- [历史](#history) +- [CloudEvents 概念](#cloudevents-concepts) +- [设计目标](#design-goals) +- [架构](#architecture) +- [属性版本](#versioning-of-attributes) +- [CloudEvent 属性](#cloudevent-attributes) +- [CloudEvent 属性扩展](#cloudevent-attribute-extensions) +- [生产 CloudEvents](#creating-cloudevents) +- [Qualifying 协议和编码](#qualifying-protocols-and-encodings) +- [Proprietary 协议和编码](#proprietary-protocols-and-encodings) - [Prior Art](#prior-art) - [Roles](#roles) - [Value Proposition](#value-proposition) - [Existing Event Formats](#existing-event-formats) -## History +## 历史 -The [CNCF Serverless Working group](https://github.com/cncf/wg-serverless) was -originally created by the CNCF's -[Technical Oversight Committee](https://github.com/cncf/toc) to investigate +[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless)是由 CNCF的 +[技术监管委员会](https://github.com/cncf/toc) to investigate Serverless Technology and to recommend some possible next steps for some CNCF related activities in this space. One of the recommendations was to investigate the creation of a common event format to aid in the portability of functions From 216791a01afa05a20b511c3cfe7c290df4f220d4 Mon Sep 17 00:00:00 2001 From: JieDing Date: Sun, 7 Nov 2021 00:05:10 +0800 Subject: [PATCH 03/60] update contents --- README.md | 5 +- primer.md | 141 ++++++++++++++++++++++-------------------------------- 2 files changed, 57 insertions(+), 89 deletions(-) diff --git a/README.md b/README.md index 5396058f1..035a7b928 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,6 @@ in Chinese for people who are new to CloudEvents. Most of the content is translated from the original English version. It is strongly recommended to read the English version if you find anything lost in translation. -声明：这份中文手册旨在帮助初次接触CloudEvents的人快速建立起CloudEvents的相关认知。 -手册中的大部分内容翻译自英文版的CloudEvents标准，当你遇到令你困惑的内容时，请对照英文版理解。 - 事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。它同样限制了那些用来帮助事件数据完成 @@ -20,7 +17,7 @@ CloudEvents是一个以通用格式来描述事件数据的标准。它提供了 CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvents被[云原生计算基金会](https://cncf.io) (CNCF)持有， 在[2018/05/15](https://docs.google.com/presentation/d/1KNSv70fyTfSqUerCnccV7eEC_ynhLsm9A_kjnlmU_t0/edit#slide=id.g37acf52904_1_41) -被选为云原生沙盒级项目。 +被选为云原生沙箱级项目。 ## CloudEvents 文件 diff --git a/primer.md b/primer.md index 5556eb330..85c4b51d6 100644 --- a/primer.md +++ b/primer.md @@ -26,103 +26,74 @@ ## 历史 [CNCF Serverless 工作组](https://github.com/cncf/wg-serverless)是由 CNCF的 -[技术监管委员会](https://github.com/cncf/toc) to investigate -Serverless Technology and to recommend some possible next steps for some CNCF -related activities in this space. One of the recommendations was to investigate -the creation of a common event format to aid in the portability of functions -between Cloud providers and the interoperability of processing of event streams. -As a result, the CloudEvents specification was created. +[技术监管委员会](https://github.com/cncf/toc) 成立，用于研究 +Serverless相关技术并为CNCF推荐相关领域的未来发展计划。其中一项建议就是研究创建一种通用事件格式， +用于提升不同云厂商间函数的可移植性和事件流处理的互操作性。就此，CloudEvents应运而生。 -While initially the work on CloudEvents was done as part of the Serverless -Working group, once the specification reached its v0.1 milestone, the TOC -approved the CloudEvents work as a new stand-alone CNCF sandbox project. +尽管CloudEvents起初是作为Serverless工作组的项目进行的，但随着CloudEvents规范完成它v0.1版本的里程碑， +技术监管委员会批准了CloudEvents工作作为一个新的独立的CNCF沙箱级项目。 -## CloudEvents Concepts +## CloudEvents 概念 -An [event](spec.md#event) includes context and data about an -[occurrence](spec.md#occurrence). Each _occurrence_ is uniquely identified by -the data of the _event_. +一个[事件](spec.md#event)包含了[事件发生](spec.md#occurrence)的上下文和相关数据。 +事件的相关数据可以用来唯一标识一件事件的发生。 -_Events_ represent facts and therefore do not include a destination, whereas -messages convey intent, transporting data from a source to a given destination. +事件代表了已发生的事实，因此它并不包含任何目的地相关信息，但消息能够传达事件内容，从而将事件数据 +从源头传输到指定的目的地。 -### Eventing +### 事件使用 -Events are commonly used in server-side code to connect disparate systems where -the change of state in one system causes code to execute in another. For -example, a source may generate an event when it receives an external signal -(e.g. HTTP or RPC) or observes a changing value (e.g. an IoT sensor or period of -inactivity). +事件通常在服务器端代码中使用来连接不同的系统，其中一个系统中的状态变化会导致代码在另一个系统中执行。 +比如，一个事件源，可能会在收到某个外部信号(如HTTP或RPC)或观察到状态变化(如IoT传感器数据变化或不活跃) +时，生产一个事件。 -To illustrate how a system uses CloudEvents, the simplified diagram below shows -how an event from a [source](spec.md#source) triggers an action. +为了更好地解释一个系统如何使用CloudEvents，下图展示了一个从事件源生产的事件是如何触发一个行为的。 ![alt text](source-event-action.png "A box representing the source with arrow pointing to a box representing the action. The arrow is annotated with 'e' for event and 'protocol'.") -The source generates a message where the event is encapsulated in a protocol. -The event arrives to a destination, triggering an action which is provided with -the event data. - -A _source_ is a specific instance of a source-type which allows for staging and -test instances. Open source software of a specific _source-type_ may be deployed -by multiple companies or providers. - -Events can be delivered through various industry standard protocols (e.g. HTTP, -AMQP, MQTT, SMTP), open-source protocols (e.g. Kafka, NATS), or platform/vendor -specific protocols (AWS Kinesis, Azure Event Grid). - -An action processes an event defining a behavior or effect which was triggered -by a specific _occurrence_ from a specific _source_. While outside of the scope -of the specification, the purpose of generating an _event_ is typically to allow -other systems to easily react to changes in a source that they do not control. -The _source_ and action are typically built by different developers. Often the -_source_ is a managed service and the _action_ is custom code in a serverless -Function (such as AWS Lambda or Google Cloud Functions). - -## Design Goals - -CloudEvents are typically used in a distributed system to allow for services to -be loosely coupled during development, deployed independently, and later can be -connected to create new applications. - -The goal of the CloudEvents specification is to define interoperability of event -systems that allow services to produce or consume events, where the producer and -consumer can be developed and deployed independently. A producer can generate -events before a consumer is listening, and a consumer can express an interest in -an event or class of events that is not yet being produced. Note that the -specifications produced by this effort are focused on interoperability of the -event format and how it appears while being sent on various protocols, such as -HTTP. The specifications will not focus on the processing model of either the -event producer or event consumer. - -CloudEvents, at its core, defines a set of metadata, called attributes, about -the event being transferred between systems, and how those pieces of metadata -should appear in that message. This metadata is meant to be the minimal set of -information needed to route the request to the proper component and to -facilitate proper processing of the event by that component. So, while this -might mean that some of the application data of the event itself might be -duplicated as part of the CloudEvent's set of attributes, this is to be done -solely for the purpose of proper delivery, and processing, of the message. Data -that is not intended for that purpose should instead be placed within the event -(`data`) itself. - -Additionally, it is assumed that the metadata needed by the protocol layer to -deliver the message to the target system is handled entirely by the protocol -and therefore is not included within the CloudEvents attributes. See the -[Non-Goals](#non-goals) section for more details. - -Along with the definition of these attributes, there will also be specifications -of how to serialize the event in different formats (e.g. JSON) and protocols -(e.g. HTTP, AMQP, Kafka). - -Batching of multiple events into a single API call is natively supported by some -protocols. To aid interoperability, it is left up to the protocols if and how -batching is implemented. Details may be found in the protocol binding or in the -protocol specification. A batch of CloudEvents carries no semantic meaning and -is not ordered. An [Intermediary](spec.md#intermediary) can add or remove -batching as well as assign events to different batches. +事件源生产了一条封装了基于某种协议的事件数据的消息。 +当载有事件的消息到达目的地时，会触发一个使用了事件数据的行为函数。 + +一个事件源是那些允许暂存和测试实例的源类型的特定实例。 +某个特定源类型的开源软件可能由多个公司或提供商部署。 + +事件可以通过各种行业标准协议（如HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或 +平台/供应商专有协议（AWS Kinesis、Azure Event Grid）传输。 + +一个操作函数能够处理那些定义了行为或影响的事件，这些行为和效果由来自特定来源的特定事件触发而来。 +虽然超出了规范的范围，但生成事件的目的通常是让其他系统能够轻松地对它们无法控制的源中的更改做出反应。 +源和操作通常由不同的开发人员构建。 +通常，源是托管服务，而操作是serverless函数（如 AWS Lambda 或 Google Cloud Functions）中 +的自定义代码。 + +## 设计目标 + +CloudEvents 通常用于分布式系统，以允许服务在开发过程中松耦合，独立部署，之后可以连接以创建新的应用程序。 + +CloudEvents 规范的目标是定义允许服务生产或消费事件的事件系统的互操作性， +其中生产者和消费者可以独立开发和部署。 生产者可以在没有消费者监听时就生成事件， +消费者也可以表达对尚未生成的事件或事件类的兴趣。值得注意的是，这项工作产生的规范侧重于事件格式的互操作性 +以及它在通过各种协议（例如 HTTP）发送时的显示方式。我们不关注事件生产者或事件消费者的处理模型。 + +CloudEvents的核心规范中定义了一组称之为属性的元数据， +它们描述了在系统之间传输的事件以及这些元数据片段应如何显示在该消息中。 +这些元数据是，将请求路由到适当组件并帮助该组件正确处理事件，所需的最小信息集。 +因此，某些事件本身的数据可能会作为 CloudEvent 属性集的一部分而被复制， +但这样做仅是为了能够正确传递和处理消息。那些不用于该目的的数据应放置在事件（数据）本身中。 + +此外，本规范中假设协议层所需，用来将消息传递到目标系统的元数据应完全由协议处理， +因此不包含在 CloudEvents 属性中。 有关更多详细信息，请参阅非目标部分。 + +除了这些属性的定义之外，规范还描述了关于如何序列化 +不同格式（例如 JSON）和协议（例如 HTTP、AMQP、Kafka）事件。 + +一些协议本身支持将多个事件批处理到单个 API 调用中。 +为了提升系统间的互操作性，是否以及如何实现批处理将由协议自己决定。 +相关详细信息可以在协议绑定或协议规范中找到。 +成批的CloudEvents并没有语义，也没有排序。 +[中间人](spec.md#intermediary)可以添加或删除批处理以及将事件分配给不同的批处理。 ### Non-Goals From b97d552d99e5bea1dee0396644507ab54c3ae57d Mon Sep 17 00:00:00 2001 From: JieDing Date: Sun, 7 Nov 2021 21:34:51 +0800 Subject: [PATCH 04/60] Update primer.md --- primer.md | 210 +++++++++++++++++++++++------------------------------- 1 file changed, 90 insertions(+), 120 deletions(-) diff --git a/primer.md b/primer.md index 85c4b51d6..79a3916e1 100644 --- a/primer.md +++ b/primer.md @@ -95,132 +95,102 @@ CloudEvents的核心规范中定义了一组称之为属性的元数据， 成批的CloudEvents并没有语义，也没有排序。 [中间人](spec.md#intermediary)可以添加或删除批处理以及将事件分配给不同的批处理。 -### Non-Goals - -The following are considered beyond the scope of the specification: - -- Function build and invocation process -- Language-specific runtime APIs -- Selecting a single identity/access control system -- Inclusion of protocol-level routing information -- Event persistence processes - -The CloudEvents spec will not include protocol-level routing information (e.g. -a destination URL to which the event is being sent). This is a common suggestion -by those new to the concepts of CloudEvents. After much deliberation, the -working group has come to the conclusion that routing is unnecessary in the -spec: any protocol (e.g. HTTP, MQTT, XMPP, or a Pub/Sub bus) already -defines semantics for routing. For example, the CloudEvents -[HTTP binding](http-protocol-binding.md) dictates headers and request body -contents. CloudEvents don't need to include a destination URL in the spec to be -HTTP compatible; the HTTP spec already includes one in the -[Request-Line](https://tools.ietf.org/html/rfc2616#section-5.1). - -Routing information is not just redundant, it detracts. CloudEvents should -increase interoperability and decouple the producer and consumer of events. -Prohibiting routing information from the events format allows CloudEvents to be -redelivered to new actions, or to be delivered over complex relays that include -multiple channels. For example, a CloudEvent that was intended for a webhook -should be deliverable to a dead-letter queue if the webhook address is -unavailable. That dead-letter queue should be able to feed events to new actions -that the original event emitter never imagined. - -The CloudEvents that are produced and consumed within and across systems trigger -behaviors that derive value. As such, archiving and/or replaying events can be -valuable for debugging or replication purposes. However, persisting an event -removes the contextual information available during transmission such as the -identity and rights of the producer, fidelity validation mechanisms, or -confidentiality protections. Additionally, persistence can add complexity and -challenge to meeting user's requirements. For example, the repeated use of a -private key for encryption or signing purposes increases the information -available to attackers and thereby reduces security. It is expected that -attributes may be defined that facilitate meeting persistence requirements but -it is expected that these will continuously evolve along with industry best -practices and advancements. +### 非目标 + +以下内容不在本规范的范围之内： + +- 函数的构建和调用过程 +- 特定语言的运行时 APIs +- 选择单一身份认证或访问控制的系统 +- 包含协议级路由信息 +- 事件持久化过程 + +就连那些刚接触 CloudEvents 概念的人都普遍建议 +CloudEvents 规范不应包括协议级路由信息（例如，将事件发送到的目标的URL）。 +经过深思熟虑，工作组得出的结论是，CloudEvents规范中不需要路由信息： +因为任何现有的协议（例如 HTTP、MQTT、XMPP 或 Pub/Sub 总线）都已经定义了路由语义。 +例如，CloudEvents [HTTP 绑定](http-protocol-binding.md) 规定了头部和请求正文内容。 +CloudEvents 不需要在规范中包含目标 URL 即可与 HTTP 兼容；HTTP 规范已经在 +[请求行](https://tools.ietf.org/html/rfc2616#section-5.1) 中包含了所需的目标URL。 + +路由信息不仅是多余的，而且是有害的。 +CloudEvents 应该增加互操作性并解耦事件的生产者和消费者。 +禁止来自事件格式的路由信息允许将 CloudEvents 重新传送到新操作，或通过包含多个通道的复杂中继传送。 +例如，如果 Webhook 地址不可用，则用于 Webhook 的 CloudEvent 应可传送到死信队列。 +死信队列应该能够将事件提供给原始事件发射器从未想象过的新操作。 + +在系统内和跨系统生产和消费的 CloudEvent能够触发产生价值的行为。 +因此，对于调试或复制的目的而言，存档和或重放事件可能很有价值。 +但是，持久化事件会删除传输期间可用的上下文信息，例如生产者的身份和权利、保真验证机制或机密性保护。 +此外，持久化会增加满足用户需求的复杂性和挑战。 +例如，出于加密或签名目的重复使用私钥会增加攻击者可用的信息，从而降低安全性。 +因此我们推测，可以定义有助于满足持久性要求的属性，但这些属性可能随着行业最佳实践和进步而不断发展。 ## Architecture +CloudEvents 规范集定义了四种有助于形成分层架构模型的不同类型的协议元素。 +基本规范定义了一个抽象信息模型，该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 -The CloudEvents specification set defines four different kinds of protocol -elements that form a layered architecture model. - -1. The [base specification](spec.md) defines an abstract information model made - up of attributes (key-value pairs) and associated rules for what constitutes - a CloudEvent. -2. The [extensions](./spec.md#extension-context-attributes) add use-case - specific and potentially overlapping sets of extension attributes and - associated rules, e.g. to support different tracing standards. -3. The event format encodings, e.g. [JSON](json-format.md), define how the - information model of the base specification together with the chosen - extensions is encoded for mapping it to header and payload elements of an - application protocol. -4. The protocol bindings, e.g. [HTTP](http-protocol-binding.md), defines how - the CloudEvent is bound to an application protocol's transport frame, in the - case of HTTP to the HTTP message. The protocol binding does not constrain - how the transport frame is used, meaning that the HTTP binding can be used - with any HTTP method and with request and response messages. - -If required to assure broader interoperability, the CloudEvents specification -set provides specific constraints for event delivery using a particular -application protocol. The [HTTP Webhook](http-webhook.md) specification is not -specific to CloudEvents and can be used to post any kind of one-way event and -notifications to a conformant HTTP endpoint. However, the lack of such a -specification elsewhere makes it necessary for CloudEvents to define it. - -### Protocol Error Handling - -The CloudEvents specification, for the most part, does not dictate a processing -model associated with the creation or processing of CloudEvents. As such, if -there are errors during the processing of a CloudEvent, the software -encountering the error is encouraged to use the normal protocol-level error -reporting to report them. - -## Versioning of Attributes - -For certain CloudEvents attributes, the entity or data model referenced by its -value might change over time. For example, `dataschema` might reference one -particular version of a schema document. Often these attribute values will then -distinguish each variant by including some version-specific string as part of -its value. For example, a version number (`v1`, `v2`), or a date (`2018-01-01`) -might be used. - -The CloudEvents specification does not mandate any particular pattern to be -used, or even the use of version strings at all. This decision is up to each -event producer. However, when a version-specific string is included, care should -be taken whenever its value changes as event consumers might be reliant on the -existing value and thus a change could be interpreted as a "breaking change". -Some form of communication between producers and consumers should be established -to ensure the event consumers know what possible values might be used. In -general, this is true for all CloudEvents attributes as well. - -## CloudEvent Attributes - -This section provides additional background and design points related to some of -the CloudEvent attributes. +1. [基本规范](spec.md) 定义了一个抽象信息模型， + 该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 +2. [扩展](./spec.md#extension-context-attributes) + 添加了特定于用例且可能重叠的扩展属性集和相关规则，如支持不同的追踪标准的规则。 +3. 事件格式编码,如 [JSON](json-format.md), 定义了基本规范的信息模型与所选扩展的编码方式， + 以将其映射到应用程序协议的头部和负载元素。 +4. 协议绑定, 如. [HTTP协议绑定](http-protocol-binding.md), + 在HTTP to HTTP的情况下， + 定义了 CloudEvent 如何绑定到应用程序协议的传输层 。 + 协议绑定不限制传输层的使用方式，这意味着 HTTP绑定可用于任何 HTTP方法以及请求和响应消息。 + +为了确保更广泛的互操作性，CloudEvents规范集为使用专有应用协议的事件传输提供了特定约束。 +[HTTP Webhook](http-webhook.md)规范并非特定于 CloudEvents， +而是可用于将任何类型的单向事件和通知发布到符合标准的 HTTP 端点。 +但是，由于其他地方缺乏此类规范，因此 CloudEvents 需要对其进行定义。 + +### 协议错误处理 + +CloudEvents 规范在很大程度上并未规定与 CloudEvents 的创建或处理相关联的处理模型。 +因此，如果在处理 CloudEvent 过程中出现错误， +请使用正常的协议级错误处理机制进行处理。 + +## 属性版本 + +对于某些 CloudEvents 属性，由其值引用的实体或数据模型可能会随时间变化。 +例如，`dataschema`可能引用模式文档的一个特定版本。 +通常，这些属性值会通过将一些特定于版本的字符串作为其值的一部分来区分每个变体。 +例如，可能会加入版本号 (v1, v2) 或日期 (2018-01-01)来区分。 + +CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强制使用版本字符串。 +是否使用完全取决于每个事件生产者。 +但是，当使用特定版本的字符串时，每当其值发生变化时都应注意， +因为事件消费者可能依赖于现有值，因此更改可能被解释为“破坏性更改”。 +应该在生产者和消费者之间建立某种形式的通信，以确保事件消费者知道能使用哪些可能的值。 +通常，这也适用于所有 CloudEvents 属性。 + +## CloudEvent 属性 + +本节介绍了与CloudEvent 属性相关的其他背景和设计要点。 ### id -The `id` attribute is meant to be a value that is unique across all events -related to one event source (where each event source is uniquely identified by -its CloudEvents `source` attribute value). While the exact value used is -producer defined, receivers of CloudEvents from a single event source can be -assured that no two events will share the same `id` value. The only exception to -this is if some replay of the event is supported, and in those cases, the `id` -can then be used to detect this. - -Since a single occurrence may result in the generation of more than one event, -in the cases where all of those events are from the same event source, each -CloudEvent constructed will have a unique `id`. Take the example of the creation -of a DB entry, this one occurrence might generate a CloudEvent with a type of -`create` and a CloudEvent with a type of `write`. Each of those CloudEvents -would have a unique `id`. If there is the desire for some correlation between -those two CloudEvents to indicate they are both related to the same occurrence, -then some additional data within the CloudEvent would be used for that purpose. - -In this respect, while the exact value chosen by the event producer might be -some random string, or a string that has some semantic meaning in some other -context, for the purposes of this CloudEvent attribute those meanings are not -relevant and therefore using `id` for some other purpose beyond uniqueness -checking is out of scope of the specification and not recommended. +`id` 属性是一个在同一事件源下所有事件中用来标识事件唯一的值 +（其中每个事件源由其 CloudEvents `source`属性唯一标识）。 +虽然`id`使用的确切值是生产者定义的， +但可以确保来自单个事件源的 CloudEvents 消费者不会有两个事件共享相同的 id 值。 +唯一的例外是如果支持事件的重播，在这些情况下，可以使用 id 来检测这一点。 + +由于一次事件的发生可能导致生成多个cloud event， +在所有这些事件都来自同一事件源的情况下， +生成的每个 CloudEvent 将具有唯一的 `id`。 +以创建数据库条目为例，这一事件的发生可能会生成一个类型为 create 的 CloudEvent +和一个类型为 write 的 CloudEvent。 +这两个 CloudEvents 各自都有一个唯一的 ID。 +如果需要在这两个 CloudEvent 之间建立某种关联以表明它们都与同一事件相关， +那么可以使用 CloudEvent 中的一些附加数据来实现该目的。 + +从这方面来看，虽然事件生产者对`id`的使用可能是某个随机字符串， +或者在其他上下文中具有某种语义的字符串， +但对于此 CloudEvent 属性而言，这些含义并不成立， +因此本规范不建议将 `id` 用于除了唯一性检查之外的其他目的。 ## CloudEvent Attribute Extensions From f3cf546543180902292db625815b82ebc7808016 Mon Sep 17 00:00:00 2001 From: JieDing Date: Mon, 8 Nov 2021 11:24:27 +0800 Subject: [PATCH 05/60] Update primer.md --- primer.md | 353 +++++++++++++++++++++++------------------------------- 1 file changed, 148 insertions(+), 205 deletions(-) diff --git a/primer.md b/primer.md index 79a3916e1..e8ea85e9b 100644 --- a/primer.md +++ b/primer.md @@ -8,7 +8,7 @@ ## 目录 -- [历史](#history) +- [历史](#历史) - [CloudEvents 概念](#cloudevents-concepts) - [设计目标](#design-goals) - [架构](#architecture) @@ -16,7 +16,7 @@ - [CloudEvent 属性](#cloudevent-attributes) - [CloudEvent 属性扩展](#cloudevent-attribute-extensions) - [生产 CloudEvents](#creating-cloudevents) -- [Qualifying 协议和编码](#qualifying-protocols-and-encodings) +- [合格的协议与编码](#qualifying-protocols-and-encodings) - [Proprietary 协议和编码](#proprietary-protocols-and-encodings) - [Prior Art](#prior-art) - [Roles](#roles) @@ -188,210 +188,153 @@ CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强 那么可以使用 CloudEvent 中的一些附加数据来实现该目的。 从这方面来看，虽然事件生产者对`id`的使用可能是某个随机字符串， -或者在其他上下文中具有某种语义的字符串， +或者在其它上下文中具有某种语义的字符串， 但对于此 CloudEvent 属性而言，这些含义并不成立， -因此本规范不建议将 `id` 用于除了唯一性检查之外的其他目的。 - -## CloudEvent Attribute Extensions - -In order to achieve the stated goals, the specification authors will attempt to -constrain the number of metadata attributes they define in CloudEvents. To that -end, attributes defined by this project will fall into three categories: - -- required -- optional -- extensions - -As the category names imply, "required" attributes will be the ones that the -group considers vital to all events in all use cases, while "optional" ones will -be used in a majority of the cases. Both of the attributes in these cases will -be defined within the specification itself. - -When the group determines that an attribute is not common enough to fall into -those two categories but would still benefit from the level of interoperability -that comes from being well-defined, then they will be placed into the -"extensions" category and put into -[documented extensions](documented-extensions.md). The specification defines how -these extension attributes will appear within a CloudEvent. - -In determining which category a proposed attribute belongs, or even if it will -be included at all, the group uses use-cases and user-stories to explain the -rationale and need for them. This supporting information will be added to the -[Prior Art](#prior-art) section of this document. - -Extension attributes to the CloudEvent specification are meant to be additional -metadata that needs to be included to help ensure proper routing and processing -of the CloudEvent. Additional metadata for other purposes, that is related to -the event itself and not needed in the transportation or processing of the -CloudEvent, should instead be placed within the proper extensibility points of -the event (`data`) itself. - -Extension attributes should be kept minimal to ensure the CloudEvent can be -properly serialized and transported. For example, the Event producers should -consider the technical limitations that might be encountered when adding -extensions to a CloudEvent. For example, the -[HTTP Binary Mode](http-protocol-binding.md#31-binary-content-mode) uses HTTP -headers to transport metadata; most HTTP servers will reject requests with -excessive HTTP header data, with limits as low as 8kb. Therefore, the aggregate -size and number of extension attributes should be kept minimal. - -If an extension becomes popular then the specification authors might consider -moving it into the specification as a core attribute. This means that the -extension mechanism/process can be used as a way to vet new attributes prior to -formally adding them to the specification. - -### JSON Extensions - -As mentioned in the [Attributes](json-format.md#2-attributes) section of the -[JSON Event Format for CloudEvents](json-format.md) specification, CloudEvent -extension attributes are serialized as siblings to the specification defined -attributes - meaning, at the top-level of the JSON object. The authors of the -specification spent a long time considering all options and decided that this -was the best choice. Some of the rationale follows. - -Since the specifications follow [semver](https://semver.org/), this means that -new properties can be defined by future versions of the core specification -without requiring a major version number change - as long as these properties -are optional. In those cases, consider what an existing consumer would do with a -new (unknown) top-level property. While it would be free to ignore it, since it -is optional, in most cases it is believed that these properties would still want -to be exposed to the application receiving those events. This would allow those -applications to support these properties even if the infrastructure doesn't. -This means that unknown top-level properties (regardless of who defined them - -future versions of the spec or the event producer) are probably not going to be -ignored. So, while some other specifications define a specific property under -which extensions are placed (e.g. a top-level `extensions` property), the -authors decided that having two different locations within an incoming event for -unknown properties could lead to interoperability issues and confusion for -developers. - -Often extensions are used to test new potential properties of specifications -prior to them being formally adopted. If there were an `extensions` type of -property, in which this new property was serialized, then if that property were -to ever be adopted by the core specification it would be promoted (from a -serialization perspective) from the `extensions` property to be a top-level -property. If we assume that this new property will be optional, then as it is -adopted by the core specification it will be just a minor version increment, and -all existing consumers should still continue to work. However, consumers will -not know where this property will appear - in the `extensions` property or as a -top-level property. This means they might need to look in both places. What if -the property appears in both place but with different values? Will producers -need to place it in both places since they could have old and new consumers? -While it might be possible to define clear rules for how to solve each of the -potential problems that arise, the authors decided that it would be better to -simply avoid all of them in the first place by only having one location in the -serialization for unknown, or even new, properties. It was also noted that the -HTTP specification is now following a similar pattern by no longer suggesting -that extension HTTP headers be prefixed with `X-`. - -## Creating CloudEvents - -The CloudEvents specification purposely avoids being too prescriptive about how -CloudEvents are created. For example, it does not assume that the original event -source is the same entity that is constructing the associated CloudEvent for -that occurrence. This allows for a wide variety of implementation choices. -However, it can be useful for implementors of the specification to understand -the expectations that the specification authors had in mind as this might help -ensure interoperability and consistency. - -As mentioned above, whether the entity that generated the initial event is the -same entity that creates the corresponding CloudEvent is an implementation -choice. However, when the entity that is constructing/populating the CloudEvents -attributes is acting on behalf of the event source, the values of those -attributes are meant to describe the event or the event source and not the -entity calculating the CloudEvent attribute values. In other words, when the -split between the event source and the CloudEvents producer are not materially -significant to the event consumers, the spec defined attributes would typically -not include any values to indicate this split of responsibilities. - -This isn't to suggest that the CloudEvents producer couldn't add some additional -attributes to the CloudEvent, but those are outside the scope of the -interoperability defined attributes of the spec. This is similar to how an HTTP -proxy would typically minimize changes to the well-defined HTTP headers of an -incoming message, but it might add some additional headers that include -proxy-specific metadata. - -It is also worth noting that this separation between original event source and -CloudEvents producer could be small or large. Meaning, even if the CloudEvent -producer were not part of the original event source's ecosystem, if it is acting -on behalf of the event source, and its presence in the flow of the event is not -meaningful to event consumers, then the above guidance would still apply. - -When an entity is acting as both a receiver and sender of CloudEvents for the -purposes of forwarding, or transforming, the incoming event, the degree to which -the outbound CloudEvent matches the inbound CloudEvent will vary based on the -processing semantics of this entity. In cases where it is acting as proxy, where -it is simply forwarding CloudEvents to another event consumer, then the outbound -CloudEvent will typically look identical to the inbound CloudEvent with respect -to the spec defined attributes - see previous paragraph concerning adding -additional attributes. - -However, if this entity is performing some type of semantic processing of the -CloudEvent, typically resulting in a change to the value of the `data` -attribute, then it may need to be considered a distinct "event source" from the -original event source. And as such, it is expected that CloudEvents attributes -related to the event producer (such as `source` and `id`) would be changed from -the incoming CloudEvent. - -## Qualifying Protocols and Encodings - -The explicit goal of the CloudEvents effort, as expressed in the specification, -is "describing event data in a common way" and "to define interoperability of -event systems that allow services to produce or consume events, where the -producer and consumer can be developed and deployed independently". - -The foundations for such interoperability are open data formats and open -protocols, with CloudEvents aiming to provide such an open data format and -projections of its data format onto commonly used protocols and with commonly -used encodings. - -While each software or service product and project can obviously make its own -choices about which form of communication it prefers, its unquestionable that a -proprietary protocol that is private to such a product or project does not -further the goal of broad interoperability across producers and consumers of -events. - -Especially in the area of messaging and eventing, the industry has made -significant progress in the last decade in developing a robust and broadly -supported protocol foundation, like HTTP 1.1 and HTTP/2 as well as WebSockets or -events on the web, or MQTT and AMQP for connection-oriented messaging and -telemetry transfers. - -Some widely used protocols have become de-facto standards emerging out of strong -ecosystems of top-level consortia of three or more companies, and some out of -the strong ecosystems of projects released by a single company, and in either -case largely in parallel to the evolution of the previously mentioned standards -stacks. - -The CloudEvents effort shall not become a vehicle to even implicitly endorse or -promote project- or product-proprietary protocols, because that would be -counterproductive towards CloudEvents' original goals. - -For a protocol or encoding to qualify for a core CloudEvents event format or -protocol binding, it must belong to either one of the following categories: - -- The protocol has a formal status as a standard with a widely-recognized - multi-vendor protocol standardization body (e.g. W3C, IETF, OASIS, ISO) -- The protocol has a "de-facto standard" status for its ecosystem category, - which means it is used so widely that it is considered a standard for a given - application. Practically, we would like to see at least one open source - implementation under the umbrella of a vendor-neutral open-source organization - (e.g. Apache, Eclipse, CNCF, .NET Foundation) and at least a dozen independent - vendors using it in their products/services. - -Aside from formal status, a key criterion for whether a protocol or encoding -shall qualify for a core CloudEvents event format or protocol binding is -whether the group agrees that the specification will be of sustained practical -benefit for any party that is unrelated to the product or project from which the -protocol or encoding emerged. A base requirement for this is that the protocol -or encoding is defined in a fashion that allows alternate implementations -independent of the product or project's code. - -All other protocol and encoding formats for CloudEvents are welcome to be -included in a list pointing to the CloudEvents binding information in the -respective project's own public repository or site. - -## Proprietary Protocols and Encodings +因此本规范不建议将 `id` 用于除了唯一性检查之外的其它目的。 + +## CloudEvent 属性扩展 + +为了实现规范的设计目标， +规范作者将尝试限制他们在 CloudEvents 中定义的元数据属性的数量。 +为此，该项目定义的属性将分为以下三类： + +- 必要属性 +- 可选属性 +- 扩展属性 + +正如类别名称所暗示的那样， +“必要”属性是工作组认为在任何情况下，对所有事件都至关重要的属性， +而“可选”属性将在大多数情况下使用。 这些情况下的两个属性都在本规范中定义了出来。 + +当工作组考虑到某些属性不够常见而不能归入上述两个类别， +但此类属性的良好定义仍会使系统间的互操作性级别受益， +则将这些属性放入了“扩展”类别并记录在[扩展文档](documented-extensions.md)中， +本规范定义了这些扩展属性在 CloudEvent 中的显示方式。 + +在确定提议的属性属于哪个类别时， +工作组使用现有的用例和用户故事来解释它们的基本原理和需求。 +相关信息将添加到本文档的[现有技术](#prior-art)部分。 + +CloudEvent 规范的扩展属性是需要包含的附加元数据，它们能确保合适的路由和正确处理CloudEvent。 +用于其它目的的附加元数据， +即那些与事件本身相但在 CloudEvent 的传输或处理中不需要的元数据， +应改为放置在事件 (`data`)的扩展点内。 + +扩展属性应保持最少，以确保 CloudEvent 可以正确序列化和传输。 +事件生产者应该考虑在向 CloudEvent 添加扩展时可能遇到的技术限制。 +例如，[HTTP Binary Mode](http-protocol-binding.md#31-binary-content-mode) +使用 HTTP 头来传输元数据； +大多数 HTTP 服务器会拒绝包含过多 HTTP 头部数据的请求，要求限制其低至 8kb。 +因此，扩展属性的大小和数量应保持最小。 + +如果扩展变得流行，那么规范作者可能会考虑将其作为核心属性移入规范。 +这意味着在正式将新属性添加到规范之前，扩展机制/过程可用作审查新属性的一种方式。 + +### JSON 扩展 + +如 [CloudEvents JSON 事件格式](json-format.md)中 +[属性](json-format.md#2-attributes)部分所述， +CloudEvent 扩展属性与已定义属性(必要属性、可选属性)在序列化时处于同一等级 - +也就是说，它们都是 JSON 对象的顶层属性。 +CloudEvent的作者花了很长时间考虑所有选项，并认为这是最好的选择。 +理由如下： + +由于CloudEvents规范遵循 [semver](https://semver.org/)， +这意味着只要新属性是可选属性，它们可以由核心规范的未来版本定义，而无需更改主要版本。 +在这些情况下，请考虑现有消费者将如何使用新的（未知）顶级属性。 +虽然消费者可以随意忽略它，因为它是可选的， +但在大多数情况下，这些属性仍然希望向接收这些事件的应用公开。 +这将允许这些应用程序支持这些属性，即使基础设施不支持。 +这意味着未知的顶级属性（无论是谁定义的——规范的未来版本或事件生产者）可能不会被忽略。 +因此，虽然其它一些规范定义了放置扩展的特定属性（例如顶级`extensions`属性）， +但作者认为在传入事件中具有两个不同位置的未知属性可能会导致互操作性问题和开发人员的混淆。 + +扩展属性通常用于测试那些被规范正式采用之前的潜在属性。 +如果有一个`extensions`类型的属性，这个新属性已经被序列化， +那么如果该属性被核心规范采用，它将从`extensions`属性提升（从序列化的角度）为顶级属性。 +如果我们假设这个新属性是可选的，那么当它被核心规范采用时， +它只是一个小版本增量，所有现有的消费者仍然会继续工作。 +但是，消费者将不知道此属性将出现在何处 - 在扩展属性中或是作为顶级属性。 +这意味着他们可能需要同时查看两个地方。 +如果属性出现在两个地方但具有不同的值怎么办？ +生产者是否需要将它放在两个地方，因为他们可能有新老消费者？ +虽然有可能为如何解决出现的每个潜在问题定义明确的规则， +但作者认为一个避免这些问题的更好的办法是在序列化中只有一个位置来放置未知的甚至是新的属性。 +作者还注意到 HTTP 规范现在遵循类似的模式，不再建议扩展 HTTP 头部以 X- 为前缀。 + +## 生产 CloudEvents + +CloudEvents 规范有意避免将CloudEvents 的创建方式设计的过于死板。 +例如，它不假定原始事件源必须是该事件构造关联 CloudEvent 的同一实体。 +这允许多种实现方式。 +但是，对于规范的实现者来说，理解规范作者心中的期望是很有用的，因为这将有助于确保互操作性和一致性。 + +如上所述，生成初始事件的实体是否与创建相应 CloudEvent 的实体相同是由实现决定的。 +但是，当构建/填充 CloudEvents 属性的实体代表事件源进行操作时，这些属性的值是用来描述事件或事件源， +而不是计算 CloudEvent 属性值的实体的。 +换句话说，当事件源和 CloudEvents 生产者之间的分离对事件使用者没有实质性意义时， +规范定义的属性通常不会包含任何值来指示这种职责分离。 + +这并不是说 CloudEvents 生产者不能向 CloudEvent 添加一些额外的属性， +但这些属性超出了规范的互操作性定义属性的范围。 +这类似于 HTTP 代理通常如何最大限度地减少对传入消息的明确定义的 HTTP 头部的更改， +但它可能会添加一些额外的头部，其中包括一些特定代理的元数据。 + +还值得注意的是，原始事件源和 CloudEvents 生产者之间的这种分离可大可小。 +意思是，即使 CloudEvent 生产者不是原始事件源生态系统的一部分， +如果它代表事件源行事，并且它在事件流中的存在对事件消费者没有意义，那么上述指导仍然适用。 + +当实体同时充当 CloudEvents 的接收者和发送者以转发或转换传入事件时， +出站 CloudEvent 与入站 CloudEvent 匹配的程度将根据该实体的处理语义而有所不同。 +在它充当代理的情况下，它只是将 CloudEvents 转发给另一个事件消费者， +那么出站 CloudEvent 通常看起来与入站 CloudEvent 就规范定义的属性相同 +- 请参阅上一段有关添加其他属性的内容。 + +但是，如果此实体正在执行 CloudEvent 的某种类型的语义处理， +通常会导致`data`属性值发生更改， +则可能需要将其视为与原始事件源不同的“事件源”。 +因此，预计与事件生产者相关的 CloudEvents 属性（例如`source` and `id`） +将从传入的 CloudEvent 中更改。 + +## 合格的协议与编码 + +正如规范中所表达的，CloudEvents 工作的明确目标是 +“以通用方式描述事件数据”且 +“定义允许服务产生或消费事件的事件系统的互操作性，其中生产者和消费者可以被独立开发和部署”。 + +这种互操作性的基础是开放的数据格式和协议， +CloudEvents 旨在提供这种开放的数据格式，并将其数据格式映射到常用协议和常用编码上。 + +虽然每个软件或服务产品和项目都可以自己选择自己喜欢的通信形式， +但毫无疑问，这种产品或项目私有的专有协议无法进一步实现跨生产者和消费者的广泛互操作性的目标。 + +特别是在消息传递和事件处理领域，该行业在过去十年中开发出了强大且受到广泛支持的协议 +例如 HTTP 1.1 和 HTTP/2 以及 WebSockets 或 Web 上的事件，或者 MQTT 和 AMQP +用于面向连接的消息传递和遥测传输的协议。 + +一些广泛使用的协议已经成为事实上的标准，这些协议来自三个或更多公司的顶级财团的强大生态系统， +还有一些来自单个公司发布的强大项目生态系统，在任何一种情况下都与前面提到的标准栈的演变相一致。 + +CloudEvents的努力不应成为认可或推广项目或产品专有协议的工具， +因为这与CloudEvents 的原始目标背道而驰。 + +要使协议或编码符合核心 CloudEvents 事件格式或协议绑定的条件，它必须属于以下任一类别： + +- 该协议具有广泛认可的多供应商协议标准化机构（例如 W3C、IETF、OASIS、ISO）的正式标准地位 +- 该协议在其生态系统类别中具有“事实上的标准”地位， + 这意味着它被广泛使用，甚至被认为是给定应用程序的标准。 + 实际上，我们希望在供应商中立的开源组织（例如 Apache、Eclipse、CNCF、.NET 基金会）的保护伞下 + 看到至少一个开源实现， + 并且至少有十几个独立供应商在他们的产品中使用它的产品或服务。 + +除了正式状态之外，协议或编码是否符合核心 CloudEvents 事件格式或协议绑定的一个关键标准是， +该组织是否认为协议或编码出现后，该规范对与产品或项目无关的任何一方具有持续的实际利益。 +对此的基本要求是协议或编码的定义方式允许独立于产品或项目代码的替代实现。 + +欢迎将 CloudEvents 的所有其他协议和编码格式 +包含在指向相应项目自己的公共存储库或站点中的 CloudEvents binding信息的列表中。 + +## 专有的协议与编码 To encourage adoption of CloudEvents, this repository will collect CloudEvent specs for proprietary protocols and encodings without endorsement. Repository From 15ff45d5df530510d818eea6ce5bb12272d99897 Mon Sep 17 00:00:00 2001 From: JieDing Date: Mon, 8 Nov 2021 17:18:09 +0800 Subject: [PATCH 06/60] Update primer.md --- primer.md | 468 +++++++++++++++++++++++------------------------------- 1 file changed, 195 insertions(+), 273 deletions(-) diff --git a/primer.md b/primer.md index e8ea85e9b..9681d2a84 100644 --- a/primer.md +++ b/primer.md @@ -9,18 +9,18 @@ ## 目录 - [历史](#历史) -- [CloudEvents 概念](#cloudevents-concepts) -- [设计目标](#design-goals) -- [架构](#architecture) -- [属性版本](#versioning-of-attributes) -- [CloudEvent 属性](#cloudevent-attributes) -- [CloudEvent 属性扩展](#cloudevent-attribute-extensions) -- [生产 CloudEvents](#creating-cloudevents) -- [合格的协议与编码](#qualifying-protocols-and-encodings) -- [Proprietary 协议和编码](#proprietary-protocols-and-encodings) -- [Prior Art](#prior-art) -- [Roles](#roles) -- [Value Proposition](#value-proposition) +- [CloudEvents 概念](#CloudEvents-概念) +- [设计目标](#设计目标) +- [架构](#架构) +- [属性版本](#属性版本) +- [CloudEvent 属性](#CloudEvent-属性) +- [CloudEvent 属性扩展](#CloudEvent-属性扩展) +- [生产 CloudEvents](#生产CloudEvents) +- [合格的协议与编码](#合格的协议与编码) +- [Proprietary 协议和编码](#专有的协议与编码) +- [Prior Art](#现有技术) +- [Roles](#角色) +- [Value Proposition](#价值主张) - [Existing Event Formats](#existing-event-formats) ## 历史 @@ -33,7 +33,7 @@ Serverless相关技术并为CNCF推荐相关领域的未来发展计划。其中 尽管CloudEvents起初是作为Serverless工作组的项目进行的，但随着CloudEvents规范完成它v0.1版本的里程碑， 技术监管委员会批准了CloudEvents工作作为一个新的独立的CNCF沙箱级项目。 -## CloudEvents 概念 +## CloudEvents-概念 一个[事件](spec.md#event)包含了[事件发生](spec.md#occurrence)的上下文和相关数据。 事件的相关数据可以用来唯一标识一件事件的发生。 @@ -126,7 +126,7 @@ CloudEvents 应该增加互操作性并解耦事件的生产者和消费者。 例如，出于加密或签名目的重复使用私钥会增加攻击者可用的信息，从而降低安全性。 因此我们推测，可以定义有助于满足持久性要求的属性，但这些属性可能随着行业最佳实践和进步而不断发展。 -## Architecture +## 架构 CloudEvents 规范集定义了四种有助于形成分层架构模型的不同类型的协议元素。 基本规范定义了一个抽象信息模型，该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 @@ -166,7 +166,7 @@ CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强 应该在生产者和消费者之间建立某种形式的通信，以确保事件消费者知道能使用哪些可能的值。 通常，这也适用于所有 CloudEvents 属性。 -## CloudEvent 属性 +## CloudEvent-属性 本节介绍了与CloudEvent 属性相关的其他背景和设计要点。 @@ -192,7 +192,7 @@ CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强 但对于此 CloudEvent 属性而言，这些含义并不成立， 因此本规范不建议将 `id` 用于除了唯一性检查之外的其它目的。 -## CloudEvent 属性扩展 +## CloudEvent-属性扩展 为了实现规范的设计目标， 规范作者将尝试限制他们在 CloudEvents 中定义的元数据属性的数量。 @@ -262,7 +262,7 @@ CloudEvent的作者花了很长时间考虑所有选项，并认为这是最好 但作者认为一个避免这些问题的更好的办法是在序列化中只有一个位置来放置未知的甚至是新的属性。 作者还注意到 HTTP 规范现在遵循类似的模式，不再建议扩展 HTTP 头部以 X- 为前缀。 -## 生产 CloudEvents +## 生产CloudEvents CloudEvents 规范有意避免将CloudEvents 的创建方式设计的过于死板。 例如，它不假定原始事件源必须是该事件构造关联 CloudEvent 的同一实体。 @@ -336,277 +336,200 @@ CloudEvents的努力不应成为认可或推广项目或产品专有协议的工 ## 专有的协议与编码 -To encourage adoption of CloudEvents, this repository will collect CloudEvent -specs for proprietary protocols and encodings without endorsement. Repository -maintainers are not responsible for creating, maintaining, or notifying -maintainers of proprietary specs of drift from the CloudEvents spec. - -Proprietary specs will be hosted in their own repository or documentation site, -and collected in the [proprietary-specs](proprietary-specs.md) file. Proprietary -specs should follow the same format as the other specs for core protocols and -encodings. - -Proprietary specs will receive less scrutiny than a core spec, and as the -CloudEvents spec evolves, it is the responsibility of the maintainers of the -respective protocols and encodings to keep specs in sync with the CloudEvents -spec. If a proprietary spec falls too far out of date, CloudEvents may mark the -link to that spec as deprecated or remove it. - -In the case that multiple, incompatible specs are created for the same protocol, -the repository maintainers will be agnostic about which spec is correct and list -links to all specs. - -## Prior Art - -This section describes some of the input material used by the group during the -development of the CloudEvent specification. - -### Roles - -The list below enumerates the various participants, and scenarios, that might be -involved in the producing, managing or consuming of events. - -In these the roles of event producer and event consumer are kept distinct. A -single application context can always take on multiple roles concurrently, -including being both a producer and a consumer of events. - -1. Applications produce events for consumption by other parties, for instance - for providing consumers with insights about end-user activities, state - changes or environment observations, or for allowing complementing the - application's capabilities with event-driven extensions. - - Events are typically produced related to a context or a producer-chosen - classification. For example, a temperature sensor in a room might be - context-qualified by mount position, room, floor, and building. A sports - result might be classified by league and team. - - The producer application could run anywhere, such as on a server or a device. - - The produced events might be rendered and emitted directly by the producer or - by an intermediary; as example for the latter, consider event data - transmitted by a device over payload-size-constrained networks such as - LoRaWAN or ModBus, and where events compliant to this specification will be - rendered by a network gateway on behalf of the producer. - - For example, a weather station transmits a 12-byte, proprietary event payload - indicating weather conditions once every 5 minutes over LoRaWAN. A LoRaWAN - gateway is then used to publish the event to an Internet destination in the - CloudEvents format. The LoRaWAN gateway is the event producer, publishing on - behalf of the weather station, and will set event metadata appropriately to - reflect the source of the event. - -2. Applications consume events for the purposes such as display, archival, - analytics, workflow processing, monitoring the condition and/or providing - transparency into the operation of a business solution and its foundational - building blocks. - - The consumer application could run anywhere, such as on a server or a device. - - A consuming application will typically be interested in: - - - distinguishing events such that the exact same event is not processed - twice. - - identifying and selecting the origin context or the producer-assigned - classification. - - identifying the temporal order of the events relative to the originating - context and/or relative to a wall-clock. - - understanding the context-related detail information carried in the event. - - correlating event instances from multiple event producers and send them to - the same consumer context. - - In some cases, the consuming application might be interested in: - - - obtaining further details about the event's subject from the originating - context, like obtaining detail information about a changed object that - requires privileged access authorization. For example, a HR solution might - only publish very limited information in events for privacy reasons, and - any event consumer needing more data will have to obtain details related to - the event from the HR system under their own authorization context. - - interact with the event's subject at the originating context, for instance - reading a storage blob after having been informed that this blob has just - been created. - - Consumer interests motivate requirements for which information producers - ought to include an event. - -3. Middleware routes events from producers to consumers, or onwards to other - middleware. Applications producing events might delegate certain tasks - arising from their consumers' requirements to middleware: +为了鼓励更多人采用 CloudEvents，本仓库将自动收集专有协议和编码。 +本仓库的维护人员不负责创建、维护或通知专有规范的维护人员有关专有规范和CloudEvents规范间的偏差。 + +专有规范将托管在他们自己的仓库或文档站点中，并收集在[专有规范](proprietary-specs.md) +文件中。 专有规范应遵循与核心协议和编码相关的其他规范相同的格式。 + +专有规范将比核心规范受到更少的审查，并且随着 CloudEvents 规范的发展， +相应协议和编码的维护者有责任使规范与 CloudEvents 规范保持同步。 +如果专有规范过时太多，CloudEvents 可能会将指向该规范的链接标记为已弃用或将其删除。 + +如果为同一个协议创建了多个不兼容的规范，存储库维护者将不知道哪个规范是正确的，并列出所有规范的链接。 + +## 现有技术 + +本节介绍了工作组在 CloudEvent 规范开发过程中使用的一些输入材料。 + +### 角色 + +下面列举了可能涉及事件的产生、管理或消费的各种参与者和场景。 + +在这些中，事件生产者和事件消费者的角色是不同的。 +单个应用程序上下文始终可以同时承担多个角色，包括既是事件的生产者又是事件的消费者。 + +1. 应用程序生成供他人使用的事件， + 如为消费者提供有关终端用户活动、状态变化或环境观察的见解， + 或允许通过事件驱动的扩展来补充应用程序的功能。 + + 生产的事件通常与上下文或生产者选择的分类相关。 + 例如，房间中的温度传感器可能被安装位置、房间、楼层和建筑物等上下文限定。 + 运动结果可以按联赛和球队分类。 + + 生产者应用程序可以在任何地方运行，例如在服务器或设备上。 + + 生产的事件可能由生产者或中间人直接提供和发出； + 作为后者的示例，请考虑设备通过负载大小受限的网络（如 LoRaWAN 或 ModBus）传输的事件数据， + 并且符合此规范的事件将由网络网关代表生产者提供。 + + 例如，气象站每 5 分钟通过 LoRaWAN 传输一次 12 字节的专有事件有效载荷用于指示天气状况。 + 然后使用 LoRaWAN 网关以 CloudEvents 格式将事件发布到 Internet 目标。 + LoRaWAN 网关是事件生产者，代表气象站发布事件，并将设置一定的元数据以反映事件的来源(气象站)。 + +2. 应用程序可能以以下目的： + 如显示、存档、分析、工作流处理、监控状态或提供业务解决方案及其基本构建模块的透明化 + 来消费事件。 + + 消费者应用程序可以在任何地方运行，例如在服务器或设备上。 + + 消费应用程序通常对以下内容感兴趣： + + - 区分事件，使得完全相同的事件不会被处理两次。 + - 识别和选择源上下文或生产者指定的分类。 + - 确定事件相对于原始上下文或相对于时钟的时间顺序。 + - 了解事件中携带的上下文相关的详细信息。 + - 关联来自多个事件生产者的事件实例并将它们发送到相同的消费者上下文。 + + 在某些情况下，消费应用程序可能对以下内容感兴趣： + + - 从原始上下文中获取有关事件主题的更多详细信息，例如获取有关需要特权访问授权的已更改对象的详细信息。 + 例如，出于隐私原因，HR 解决方案可能仅在事件中发布非常有限的信息， + 任何需要更多数据的事件消费者都必须在其自己的授权上下文下从 HR 系统获取与事件相关的详细信息 + - 在原始上下文中与事件的主题进行交互，例如在被告知该数据块刚刚创建后读取存储该数据块。 + + 消费者的兴趣激发了信息生产者应该包括事件的需求。 + +3. 中间件将事件从生产者路由到消费者，或转发到其他中间件。 + 产生事件的应用程序可能会将消费者需求产生的某些任务委托给中间件： - Management of many concurrent interested consumers for one of multiple classes or originating contexts of events - - Processing of filter conditions over a class or originating context of - events on behalf of consumers. - - Transcoding, like encoding in MsgPack after decoding from JSON - - Transformation that changes the event's structure, like mapping from a - proprietary format to CloudEvents, while preserving the identity and - semantic integrity of the event. - - Instant "push-style" delivery to interested consumers. - - Storing events for eventual delivery, either for pick-up initiated by the - consumer ("pull") or initiated by the middleware ("push") after a delay. - - Observing event content or event flow for monitoring or diagnostics - purposes. - - To satisfy these needs, middleware will be interested in: - - - A metadata discriminator usable for classification or contextualization of - events so that consumers can express interest in one or multiple such - classes or contexts. For instance, a consumer might be interested in all - events related to a specific directory inside a file storage account. - - A metadata discriminator that allows distinguishing the subject of a - particular event of that class or context. For instance, a consumer might - want to filter out all events related to new files ending with ".jpg" (the - file name being the "new file" event's subject) for the context describing - specific directory inside a file storage account that it has registered - interest on. - - An indicator for the encoding of the event and its data. - - An indicator for the structural layout (schema) for the event and its data. - - Whether its events are available for consumption via a middleware is a - delegation choice of the producer. - - In practice, middleware can take on the role of a - [Producer](spec.md#producer) when it changes the semantic meaning of an - event, a [Consumer](spec.md#consumer) when it takes action based on an event, - or [Intermediary](spec.md#intermediary) when it routes events without making - semantic changes. - -4. Frameworks and other abstractions make interactions with event platform - infrastructure simpler, and often provide common API surface areas for - multiple event platform infrastructures. - - Frameworks are often used for turning events into an object graph, and to - dispatch the event to some specific handling user-code or user-rule that - permits the consuming application to react to a particular kind of occurrence - in the originating context and on a particular subject. - - Frameworks are most interested in semantic metadata commonality across the - platforms they abstract, so that similar activities can be handled uniformly. - - For a sports application, a developer using the framework might be interested - in all events from today's game (subject) of a team in a league (topic of - interest) but wanting to handle reports of "goal" differently than reports of - "substitution". For this, the framework will need a suitable metadata - discriminator that frees it from having to understand the event details. - -### Value Proposition - -This section describes some of the use-cases that explain the value of -CloudEvents. - -#### Normalizing Events Across Services & Platforms - -Major event publishers (e.g. AWS, Microsoft, Google, etc.) all publish events in -different formats on their respective platforms. There are even a few cases -where services on the same provider publish events in different formats (e.g. -AWS). This forces event consumers to implement custom logic to read or munge -event data across platforms and occasionally across services on a single -platform. - -CloudEvents can offer a single experience for authoring consumers that handle -events across all platforms and services. - -#### Facilitating Integrations Across Services & Platforms - -Event data being transported across environments is increasingly common. -However, without a common way of describing events, delivery of events across -environments is hindered. There is no single way of determining where an event -came from and where it might be going. This prevents tooling to facilitate -successful event delivery and consumers from knowing what to do with event data. - -CloudEvents offers useful metadata which middleware and consumers can rely upon -to facilitate event routing, logging, delivery and receipt. - -#### Increasing Portability of Functions-as-a-Service - -Functions-as-a-Service (also known as serverless computing) is one of the -fastest growing trends in IT and it is largely event-driven. However, a primary -concern of FaaS is vendor lock-in. This lock-in is partially caused by -differences in function APIs and signatures across providers, but the lock-in is -also caused by differences in the format of event data received within -functions. - -CloudEvents' common way of describing event data increases the portability of -Functions-as-a-Service. - -#### Improving Development & Testing of Event-Driven/Serverless Architectures - -The lack of a common event format complicates development and testing of -event-driven and serverless architectures. There is no easy way to mock events -accurately for development and testing purposes, and help emulate event-driven -workflows in a development environment. - -CloudEvents can enable better developer tools for building, testing and handling -the end-to-end lifecycle of event-driven and serverless architectures. + - 代表消费者在类或事件的原始上下文上处理过滤条件。 + - 转码，比如从 JSON 解码后在 MsgPack 中编码 + - 更改事件结构的转换，例如从专有格式映射到 CloudEvents，同时保留事件的身份和语义完整性。 + - 即时“推送式”传输给感兴趣的消费者。 + - 存储最终传输的事件，用于由消费者发起的“拉”请求，或延迟后由中间件发起“推”请求。 + - 观察事件内容或事件流以进行监控或诊断。 + + 为了满足这些需求，中间件将对以下方面感兴趣： + + - 一种元数据鉴别器，可用于事件的分类或上下文化，以便消费者可以表达对一个或多个类或上下文的兴趣。 + 例如，消费者可能对文件存储帐户内的特定目录相关的所有事件感兴趣。 + - 一种元数据鉴别器，允许区分该类或上下文的特定事件的主题。例如，消费者可能希望过滤掉与以“.jpg”结尾的 + 新文件相关的所有事件（文件名是“新文件”事件的主题）， + 用于描述其已注册的文件存储帐户内的特定目录的上下文兴趣。 + - 一个事件及其数据编码的指示器。 + - 一个事件及其数据的结构布局（模式）的指示器。 + + 事件是否可通过中间件消费取决于生产者的选择。 -#### Event Data Evolution + 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec.md#producer)的角色， + 当它根据事件采取行动时可以扮演[消费者](spec.md#consumer)的角色， + 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec.md#intermediary)的角色。 + +4. 框架和其他抽象使与事件平台基础设施的交互更简单， + 并且通常为多个事件平台基础设施提供公共 API 区域。 -Most platforms and services version the data model of their events differently -(if they do this at all). This creates an inconsistent experience for publishing -and consuming the data model of events as those data models evolve. + 框架通常用于将事件转换为对象图，并将事件分派给某些特定的处理用户代码或用户规则， + 这些用户代码或用户规则允许消费应用程序对原始上下文和特定主题中的特定类型的事件做出反应。 -CloudEvents can offer a common way to version and evolve event data. This will -help event publishers safely version their data models based on best practices, -and this help event consumers safely work with event data as it evolves. + 框架最感兴趣的是跨它们抽象的平台的语义元数据通用性，以便可以统一处理类似的活动。 -#### Normalizing Webhooks + 对于体育应用程序，使用该框架的开发人员可能对联盟中一支球队今天的比赛（主题） + 的所有事件感兴趣，但希望以不同于“换人”事件的方式处理“得分”事件。 + 为此，框架将需要一个合适的元数据鉴别器，使其不必了解事件细节。 -Webhooks is a style of event publishing which does not use a common format. -Consumers of webhooks don’t have a consistent way to develop, test, identify, -validate, and overall process event data delivered via webhooks. +### 价值主张 -CloudEvents can offer consistency in webhook publishing and consumption. +本节介绍了一些能够展示 CloudEvents 价值主张的用例。 -#### Policy Enforcement +#### 跨服务和平台规范化事件 -The transiting of events between systems may need to be filtered, transformed, -or blocked due to security and policy concerns. Examples may be to prevent -ingress or egress of the events such as event data containing sensitive -information or wanting to disallow the information flow between the sender and -receiver. +主要事件发布者（例如 AWS、Microsoft、Google 等）都在各自的平台上以不同的格式发布事件。 +甚至在少数情况下，同一提供商的服务以不同格式（例如 AWS）发布事件。 +这迫使事件消费者实现自定义逻辑以跨平台读取或处理事件数据，有时甚至需要跨单个平台的多个服务处理。 -A common event format would allow easier reasoning about the data being -transited and allow for better introspection of the data. +CloudEvents 可以为那些跨平台和服务处理事件的使用者提供单一体验。 -#### Event Tracing +#### 促进跨服务和平台的集成 -An event sent from a source may result in a sequence of additional events sent -from various middleware devices such as event brokers and gateways. CloudEvents -includes metadata in events to associate these events as being part of an event -sequence for the purpose of event tracing and troubleshooting. +跨环境传输的事件数据越来越普遍。 +然而，如果没有描述事件的通用方式，跨环境的事件传递就会受到阻碍。 +CloudEvents之前没有单一的方法可以确定事件的来源和可能的去向。 +这对研究成功传输事件事件工具和消费者知道如何处理事件数据形成了巨大阻碍。 + +CloudEvents 提供有用的元数据，中间件和消费者可以依赖这些元数据来促进事件路由、日志记录、传输和接收。 + +#### 提高功能即服务的可移植性 + +功能即服务（也称为serverless计算）是 IT 中增长最快的趋势之一，它主要是由事件驱动的。 +然而，FaaS 的一个主要问题是供应商锁定。 +这种锁定部分是由函数 API 和供应商之间签名的差异引起的， +锁定同样也是由函数内接收的事件数据格式的差异引起的。 + +CloudEvents提供描述事件数据的通用方式提高了功能即服务的可移植性。 + +#### 改进事件驱动/serverless架构的开发和测试 + +缺乏通用事件格式使事件驱动和serverless架构的开发和测试变得复杂。 +没有简单的方法可以准确地为开发和测试目的模拟事件，并帮助在开发环境中模拟事件驱动的工作流。 + +CloudEvents 可以提供更好的开发工具来构建、测试和处理事件驱动和无服务器架构的端到端生命周期。 + +#### 事件数据发展 + +大多数平台和服务对其事件的数据模型进行不同的版本控制（如果他们这样做的话）。 +随着这些数据模型的发展，这会为发布和使用事件的数据模型带来不一致的体验。 + +CloudEvents 可以提供一种通用的方式来版本化和发展事件数据。 +这将帮助事件发布者根据最佳实践安全地对其数据模型进行版本控制， +并且这有助于事件消费者随着事件数据的发展安全地使用它。 + +#### 规范化 Webhook + +Webhooks 是一种不使用通用格式的来发布事件的模式。 +Webhook 的使用者没有一致的方式来开发、测试、识别、验证和整体处理通过 Webhook 传输的事件数据。 + +CloudEvents 可以提供 Webhook 发布和消费事件的一致性。 + +#### 安全策略 + +出于安全和策略考虑，可能需要过滤、转换或阻止系统之间的事件传输。 +比如可能需要防止事件的进入或退出，如包含敏感信息的事件数据或想要禁止发送方和接收方之间的信息流。 + +通用事件格式将允许更容易地推理正在传输的数据，并提供更好的数据自查。 + +#### 事件追踪 + +从源发送的事件可能会出现在一系列附加事件之间， +这些附加事件从各种中间件设备（例如事件代理和网关）发出的。 +CloudEvents 在事件中包含元数据以将这些事件关联为事件序列的一部分，以便进行事件跟踪和故障排除。 #### IoT -IoT devices send and receive events related to their functionality. For example, -a connected thermostat will send telemetry on the current temperature and could -receive events to change temperatures. These devices typically have a -constrained operating environment (cpu, memory) requiring a well-defined event -message format. In a lot of cases these messages are binary encoded instead of -textual. Whether directly from the device or transformed via a gateway, -CloudEvents would allow for a better description of the origin of the message -and the format of the data contained within the message. - -#### Event Correlation - -A serverless application/workflow could be associated with multiple events from -different event sources/producers. For example, a burglary detection -application/workflow could involve both a motion event and a door/window open -event. A serverless platform could receive many instances of each type of -events, e.g. it could receive motion events and window open events from -different houses. - -The serverless platform needs to correlate one type of event instance correctly -with other types of event instances and map a received event instance to the -correct application/workflow instance. CloudEvents will provide a standard way -for any event consumer (e.g. the serverless platform) to locate the event -correlation information/token in the event data and map a received event -instance to the correct application/workflow instance. - -### Existing Event Formats - -As with the previous section, the examination (and understanding) of the current -state of the world was very important to the group. To that end, a sampling of -existing current event formats that are used in practice today was gathered. +物联网设备会发送和接收与其功能相关的事件。 +例如，连接的恒温器将发送有关当前温度的遥测数据， +并可以接收改变温度的事件。 +这些设备通常具有受限的操作环境（cpu、内存），需要明确定义的事件消息格式。 +在很多情况下，这些消息是二进制编码的，而不是文本的。 +无论是直接来自设备还是通过网关转换，CloudEvents 都可以更好地描述消息的来源和消息中包含的数据格式。 + +#### 事件关联 + +一个serverless应用或工作流可能与来自不同事件源或事件生产者的多个事件相关联。 +例如，盗窃检测应用程序/工作流可能涉及运动事件和门/窗打开事件。 +一个serverless平台可能接收每种类型事件的许多实例，例如 它可以接收来自不同房屋的运动事件和开窗事件。 + +serverless平台需要将一种类型的事件实例与其他类型的事件实例正确关联， +并将接收到的事件实例映射到正确的应用/工作流实例。 +CloudEvents 将为任何事件使用者（例如serverless平台）提供一种标准方式， +以在事件数据中定位事件关联信息/令牌并将接收到的事件实例映射到正确的应用/工作流实例。 + +### 现有的数据格式 + +与上一节一样，对当前现状的调查（和理解）对CloudEvents 小组来说非常重要。 +为此，下面列出了在实践中被广泛使用的当前事件格式的样本。 #### Microsoft - Event Grid @@ -661,8 +584,7 @@ existing current event formats that are used in practice today was gathered. #### AWS - CloudWatch Events -A high proportion of event-processing systems on AWS are converging on the use -of this format. +AWS 上的很大一部分事件处理系统都在使用这种格式。 ``` { From 32efae892831c6b3486677f4acf46276a4d51885 Mon Sep 17 00:00:00 2001 From: JieDing Date: Mon, 8 Nov 2021 17:24:14 +0800 Subject: [PATCH 07/60] Update primer.md --- primer.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/primer.md b/primer.md index 9681d2a84..08a69951f 100644 --- a/primer.md +++ b/primer.md @@ -12,16 +12,16 @@ - [CloudEvents 概念](#CloudEvents-概念) - [设计目标](#设计目标) - [架构](#架构) -- [属性版本](#属性版本) +- [属性版本控制](#属性版本控制) - [CloudEvent 属性](#CloudEvent-属性) - [CloudEvent 属性扩展](#CloudEvent-属性扩展) - [生产 CloudEvents](#生产CloudEvents) - [合格的协议与编码](#合格的协议与编码) -- [Proprietary 协议和编码](#专有的协议与编码) -- [Prior Art](#现有技术) -- [Roles](#角色) -- [Value Proposition](#价值主张) -- [Existing Event Formats](#existing-event-formats) +- [专有的协议和编码](#专有的协议与编码) +- [现有技术](#现有技术) +- [角色](#角色) +- [价值主张](#价值主张) +- [现有的数据格式](#现有的数据格式) ## 历史 @@ -152,7 +152,7 @@ CloudEvents 规范在很大程度上并未规定与 CloudEvents 的创建或处 因此，如果在处理 CloudEvent 过程中出现错误， 请使用正常的协议级错误处理机制进行处理。 -## 属性版本 +## 属性版本控制 对于某些 CloudEvents 属性，由其值引用的实体或数据模型可能会随时间变化。 例如，`dataschema`可能引用模式文档的一个特定版本。 From 2aad82c940089164c6fc47b81700061631a09fb3 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 14:24:47 +0800 Subject: [PATCH 08/60] Update spec.md --- spec.md | 854 +++++++++++++++++++++++++------------------------------- 1 file changed, 385 insertions(+), 469 deletions(-) diff --git a/spec.md b/spec.md index 5d3899541..1f1428ec8 100644 --- a/spec.md +++ b/spec.md @@ -1,547 +1,463 @@ -# CloudEvents - Version 1.0 +# CloudEvents 核心规范- 1.0 版本 -## Abstract +## 摘要 +CloudEvents 是一个用于定义事件格式的供应商中立规范。 CloudEvents is a vendor-neutral specification for defining the format of event data. -## Table of Contents +## 目录 -- [Overview](#overview) -- [Notations and Terminology](#notations-and-terminology) -- [Context Attributes](#context-attributes) -- [Event Data](#event-data) -- [Size Limits](#size-limits) -- [Privacy & Security](#privacy-and-security) -- [Example](#example) +- [概览](#概览) +- [符号和术语](#符号和术语) +- [上下文属性](#上下文属性) +- [事件数据](#事件数据) +- [大小限制](#大小限制) +- [隐私与安全](#隐私与安全) +- [示例](#示例) -## Overview +## 概览 -Events are everywhere. However, event producers tend to describe events -differently. +事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 -The lack of a common way of describing events means developers are constantly -re-learning how to consume events. This also limits the potential for libraries, -tooling and infrastructure to aid the delivery of event data across -environments, like SDKs, event routers or tracing systems. The portability and -productivity that can be achieved from event data is hindered overall. +对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。 +它同样限制了那些用来帮助事件数据完成 跨环境传输的库(如SDKs)， +工具(如事件路由器)和基础设施(如事件追踪系统)的发展。 +总体来看，这种匮乏严重阻碍了事件数据的可移植性和生产力。 -CloudEvents is a specification for describing event data in common formats to -provide interoperability across services, platforms and systems. +CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 -Event Formats specify how to serialize a CloudEvent with certain encoding -formats. Compliant CloudEvents implementations that support those encodings MUST -adhere to the encoding rules specified in the respective event format. All -implementations MUST support the [JSON format](json-format.md). +事件格式指定如何使用某些编码格式序列化一个 CloudEvent。 +支持那些编码且兼容 CloudEvents 的实现必须遵守相应事件格式中指定的编码规则。 +所有实现都必须支持 [JSON 格式](json-format.md)。 -For more information on the history, development and design rationale behind the -specification, see the [CloudEvents Primer](primer.md) document. +有关规范背后的历史、开发和设计原理等更多信息， +请参阅 CloudEvents [入门文档](primer.md)。 -## Notations and Terminology +## 符号和术语 -### Notational Conventions +### 符号约定 -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). +本文档中的关键词 +"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 需要按照 +[RFC 2119](https://tools.ietf.org/html/rfc2119) 中的描述来理解。 -For clarity, when a feature is marked as "OPTIONAL" this means that it is -OPTIONAL for both the [Producer](#producer) and [Consumer](#consumer) of a -message to support that feature. In other words, a producer can choose to -include that feature in a message if it wants, and a consumer can choose to -support that feature if it wants. A consumer that does not support that feature -will then silently ignore that part of the message. The producer needs to be -prepared for the situation where a consumer ignores that feature. An -[Intermediary](#intermediary) SHOULD forward OPTIONAL attributes. +为清楚起见， +当一个功能被标记为“OPTIONAL”时，这意味着消息的 +[生产者](#生产者)和[消费者](#消费者) 都可以自行选择是否支持该功能。 +换句话说，生产者可以在需要时在消息中包含该功能，消费者也可以在需要时选择支持该功能。 +不支持该功能的消费者将默默地忽略该部分消息。 +生产者需要做好消费者并没有启用该功能的准备。 +[中间人](#中间人) 应当转发OPTIONAL属性。 -### Terminology +### 术语 -This specification defines the following terms: +本规范定义了下列术语 -#### Occurrence +#### 发生 -An "occurrence" is the capture of a statement of fact during the operation of a -software system. This might occur because of a signal raised by the system or a -signal being observed by the system, because of a state change, because of a -timer elapsing, or any other noteworthy activity. For example, a device might go -into an alert state because the battery is low, or a virtual machine is about to -perform a scheduled reboot. +“发生”是指在软件系统运行期间对事实状态的捕获。 +这可能是由于系统发出了信号或系统观察到信号、状态更改、计时器超时 +或任何其他值得注意的活动而发生的。 +例如，设备可能会因为电池电量低或虚拟机即将执行计划的重启而进入警报状态。 -#### Event +#### 事件 -An "event" is a data record expressing an occurrence and its context. Events are -routed from an event producer (the source) to interested event consumers. The -routing can be performed based on information contained in the event, but an -event will not identify a specific routing destination. Events will contain two -types of information: the [Event Data](#event-data) representing the Occurrence -and [Context](#context) metadata providing contextual information about the -Occurrence. A single occurrence MAY result in more than one event. +“事件”是表示"发生"及其上下文的数据记录。 +事件从事件生产者（源）路由到对它感兴趣的事件消费者。 +事件中包含的信息帮助完成路由操作，但事件不会标识特定的路由目的地。 +事件将包含两种类型的信息：表示"发生"的 [事件数据](#事件数据) +和提供有关事件的环境信息的[上下文](#上下文) 元数据。 +一次"发生"可能导致多个事件的产生。 -#### Producer +#### 生产者 -The "producer" is a specific instance, process or device that creates the data -structure describing the CloudEvent. +“生产者”是一种特定的实例、进程或设备，它能够创建用来描述CloudEvent的数据结构。 -#### Source +#### 源 -The "source" is the context in which the occurrence happened. In a distributed -system it might consist of multiple [Producers](#producer). If a source is not -aware of CloudEvents, an external producer creates the CloudEvent on behalf of -the source. +"源"是事件发生的上下文环境。在分布式系统中，它可能由多个生产者组成。 +如果一个源无法查看到CloudEvents，那么一定有有外部的生产者在代替源来生产CloudEvent。 -#### Consumer +#### 消费者 -A "consumer" receives the event and acts upon it. It uses the context and data -to execute some logic, which might lead to the occurrence of new events. +一个“消费者”会接收事件并根据事件采取一定的行为。 +它使用上下文环境和事件数据来执行一些逻辑，这可能会导致新事件的发生。 -#### Intermediary +#### 中间人 -An "intermediary" receives a message containing an event for the purpose of -forwarding it to the next receiver, which might be another intermediary or a -[Consumer](#consumer). A typical task for an intermediary is to route the event -to receivers based on the information in the [Context](#context). +一个“中间人”会接收包含事件的消息， +并将其转发给下一个接收者，但该接收者可能是另一个中间人或事件[消费者](#消费者)。 +中间人的典型任务就是根据[上下文](#context)环境中的信息将事件路由到接收者。 -#### Context +#### 上下文 -Context metadata will be encapsulated in the -[Context Attributes](#context-attributes). Tools and application code can use -this information to identify the relationship of Events to aspects of the system -or to other Events. - -#### Data - -Domain-specific information about the occurrence (i.e. the payload). This might -include information about the occurrence, details about the data that was -changed, or more. See the [Event Data](#event-data) section for more -information. +上下文环境元数据被封装在[上下文-属性](#上下文-属性)中。 +工具和应用程序代码可以使用此信息来识别事件与系统方面或事件与其他事件的关系。 -#### Event Format - -An Event Format specifies how to serialize a CloudEvent as a sequence of bytes. -Stand-alone event formats, such as the [JSON format](json-format.md), specify -serialization independent of any protocol or storage medium. Protocol Bindings -MAY define formats that are dependent on the protocol. - -#### Message - -Events are transported from a source to a destination via messages. - -A "structured-mode message" is one where the event is fully encoded using -a stand-alone event format and stored in the message body. - -A "binary-mode message" is one where the event data is stored in the message -body, and event attributes are stored as part of message meta-data. - -#### Protocol - -Messages can be delivered through various industry standard protocol (e.g. HTTP, -AMQP, MQTT, SMTP), open-source protocols (e.g. Kafka, NATS), or platform/vendor -specific protocols (AWS Kinesis, Azure Event Grid). - -#### Protocol Binding - -A protocol binding describes how events are sent and received over a given -protocol, in particular how events are mapped to messages in that protocol. - -## Context Attributes - -Every CloudEvent conforming to this specification MUST include context -attributes designated as REQUIRED, MAY include one or more OPTIONAL context -attributes and MAY include one or more extension attributes. - -These attributes, while descriptive of the event, are designed such that they -can be serialized independent of the event data. This allows for them to be -inspected at the destination without having to deserialize the event data. +#### 数据 -### Attribute Naming Convention - -The CloudEvents specifications define mappings to various protocols and -encodings, and the accompanying CloudEvents SDK targets various runtimes and -languages. Some of these treat metadata elements as case-sensitive while others -do not, and a single CloudEvent might be routed via multiple hops that involve a -mix of protocols, encodings, and runtimes. Therefore, this specification limits -the available character set of all attributes such that case-sensitivity issues -or clashes with the permissible character set for identifiers in common -languages are prevented. - -CloudEvents attribute names MUST consist of lower-case letters ('a' to 'z') or -digits ('0' to '9') from the ASCII character set. Attribute names SHOULD be -descriptive and terse and SHOULD NOT exceed 20 characters in length. - -### Type System - -The following abstract data types are available for use in attributes. Each of -these types MAY be represented differently by different event formats and in -protocol metadata fields. This specification defines a canonical -string-encoding for each type that MUST be supported by all implementations. - -- `Boolean` - a boolean value of "true" or "false". - - String encoding: a case-sensitive value of `true` or `false`. -- `Integer` - A whole number in the range -2,147,483,648 to +2,147,483,647 - inclusive. This is the range of a signed, 32-bit, twos-complement encoding. - Event formats do not have to use this encoding, but they MUST only use - `Integer` values in this range. - - String encoding: Integer portion of the JSON Number per - [RFC 7159, Section 6](https://tools.ietf.org/html/rfc7159#section-6) -- `String` - Sequence of allowable Unicode characters. The following characters - are disallowed: - - the "control characters" in the ranges U+0000-U+001F and U+007F-U+009F (both - ranges inclusive), since most have no agreed-on meaning, and some, such as - U+000A (newline), are not usable in contexts such as HTTP headers. - - code points - [identified as noncharacters by Unicode](http://www.unicode.org/faq/private_use.html#noncharacters). - - code points identifying Surrogates, U+D800-U+DBFF and U+DC00-U+DFFF, both - ranges inclusive, unless used properly in pairs. Thus (in JSON notation) - "\uDEAD" is invalid because it is an unpaired surrogate, while - "\uD800\uDEAD" would be legal. -- `Binary` - Sequence of bytes. - - String encoding: Base64 encoding per - [RFC4648](https://tools.ietf.org/html/rfc4648). -- `URI` - Absolute uniform resource identifier. - - String encoding: `Absolute URI` as defined in - [RFC 3986 Section 4.3](https://tools.ietf.org/html/rfc3986#section-4.3). -- `URI-reference` - Uniform resource identifier reference. - - String encoding: `URI-reference` as defined in - [RFC 3986 Section 4.1](https://tools.ietf.org/html/rfc3986#section-4.1). -- `Timestamp` - Date and time expression using the Gregorian Calendar. - - String encoding: [RFC 3339](https://tools.ietf.org/html/rfc3339). - -All context attribute values MUST be of one of the types listed above. -Attribute values MAY be presented as native types or canonical strings. - -A strongly-typed programming model that represents a CloudEvent or any extension -MUST be able to convert from and to the canonical string-encoding to the -runtime/language native type that best corresponds to the abstract type. - -For example, the `time` attribute might be represented by the language's native -_datetime_ type in a given implementation, but it MUST be settable providing an -RFC3339 string, and it MUST be convertible to an RFC3339 string when mapped to a -header of an HTTP message. - -A CloudEvents protocol binding or event format implementation MUST likewise be -able to convert from and to the canonical string-encoding to the corresponding -data type in the encoding or in protocol metadata fields. - -An attribute value of type `Timestamp` might indeed be routed as a string -through multiple hops and only materialize as a native runtime/language type at -the producer and ultimate consumer. The `Timestamp` might also be routed as a -native protocol type and might be mapped to/from the respective -language/runtime types at the producer and consumer ends, and never materialize -as a string. - -The choice of serialization mechanism will determine how the context attributes -and the event data will be serialized. For example, in the case of a JSON -serialization, the context attributes and the event data might both appear -within the same JSON object. - -### REQUIRED Attributes - -The following attributes are REQUIRED to be present in all CloudEvents: +关于事件的特定域信息（即有效负载）。这可能包括有关事件的信息、有关已更改数据的详细信息等。 +有关更多信息，请参阅[事件数据](#事件数据)部分。 + +#### 事件格式 + +一个事件格式会指定如何将 CloudEvent 序列化为字节序列。 +独立事件格式（例如 [JSON 格式](json-format.md)）指定独立于任何协议或存储介质的序列化。 +协议绑定可以定义依赖于协议的格式。 + +#### 消息 + +事件通过消息从源传输到目标。 + +“结构化模式消息”是一种使用独立事件格式对事件进行完全编码并存储在消息体中的消息。 + +“二进制模式消息”是将事件数据存储在消息体中，并将事件属性作为消息元数据的一部分存储下来。 + +#### 协议 + +消息可以通过各种行业标准协议 +（例如 HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或平台/供应商 +专有协议（AWS Kinesis、Azure 事件网格）传输。 + +#### 协议绑定 + +协议绑定描述了如何通过给定协议发送和接收事件，特别是如何将事件映射到该协议的消息中去。 + +## 上下文属性 + +每个符合本规范的 CloudEvent 必须包括指定为 REQUIRED 的上下文属性， +可以包括一个或多个OPTIONAL上下文属性， +并且可以包括一个或多个扩展属性。 + +这些属性虽然描述了事件，但被设计为可以独立于事件数据进行序列化。 +这允许在不反序列化事件数据的情况下，在目的检查这些上下文属性。 + +### 属性命名约定 + +CloudEvents 规范定义了到各种协议和编码的映射，随附的 CloudEvents SDK 面向各种运行时和语言。 +其中一些将元数据元素区分大小写，而另一些则不区分， +并且单个 CloudEvent 可能通过涉及到协议、编码和运行时混合的多个跃点进行路由。 +因此，本规范限制了所有属性的可用字符集，以防止区分大小写问题或与通用语言中标识符的合法字符集冲突问题。 + +CloudEvents 属性名称必须由来自 ASCII 字符集的小写字母（“a”到“z”）或数字（“0”到“9”）组成。 +属性名称应该是描述性的和简洁的，并且长度不应超过 20 个字符。 + +### 类型系统 + +以下抽象数据类型可用于属性。 +这些类型中的每一种都可以由不同的事件格式和协议元数据字段以不同的方式表示。 +本规范为所有实现必须支持的每种类型定义了规范的字符串编码。 + +- `Boolean` - “true”或“false”的布尔值。 + - 字符串编码：区分大小写的`true` 或 `false`值。 +- `Integer` -范围在 -2,147,483,648 到 +2,147,483,647 （包含）之间的整数。 + 这是有符号 32 位二进制补码编码的范围。 + 事件格式不必使用此编码，但它们必须使用在此范围内的`Integer` 值。 + - 字符串编码: 符合 + [RFC 7159, 第 6 节](https://tools.ietf.org/html/rfc7159#section-6) + JSON 数字的整数部分 +- `String` - 允许的 Unicode 字符序列。 不允许使用以下字符： + - 范围 U+0000-U+001F 和 U+007F-U+009F（包含首尾）中的“控制字符”， + 因为大多数没有商定的含义，还有一些，例如 U+000A（换行符）， 在如 HTTP 头部之类的上下文中不可用。 + -[被 Unicode 标识为非字符的](http://www.unicode.org/faq/private_use.html#noncharacters) + 代码点。 + - 被 Unicode 标识为代理项的代码点, 范围 U+D800-U+DBFF 和 U+DC00-U+DFFF（包含首尾） + , 除非被合理的用作代理对. 因此（在 JSON 符号中） + “\uDEAD”是无效的，因为它是一个未配对的代理，而“\uD800\uDEAD”是合法的。 +- `Binary` - 字节序列. + - 字符串编码: 基于 + [RFC4648](https://tools.ietf.org/html/rfc4648) 的Base64 编码。 +- `URI` - 绝对统一资源标识符。 + - 字符串编码: + [RFC 3986 第 4.3 节](https://tools.ietf.org/html/rfc3986#section-4.3) + 中定义的 `Absolute URI` 。 +- `URI-reference` - 统一资源标识符引用。 + - 字符串编码: + [RFC 3986 第 4.1 节](https://tools.ietf.org/html/rfc3986#section-4.1) + 中定义的`URI-reference` 。 +- `Timestamp` - 使用公历的日期和时间表达式。 + - 字符串编码: [RFC 3339](https://tools.ietf.org/html/rfc3339) 。 + +所有上下文属性值必须是上面列出的类型之一。 +属性值可以表示为原生类型或规范字符串。 + +当强类型编程语言表示 CloudEvent 或任何扩展时， +必须能够在规范字符串编码与对应抽象类型的运行时/编程语言类型之间进行转换。 + +例如，在给定的实现中，`time` 属性可能由编程语言的本地时间类型表示， +但它必须是可设置提供 RFC3339 字符串的， +并且当映射到 HTTP 消息头时，它必须可转换为 RFC3339 字符串。 + +CloudEvents 协议绑定或事件格式实现同样必须能够 +在规范字符串编码与协议元数据字段中的对应数据类型之间进行转换。 + +`Timestamp` 类型的属性值确实可能以字符串形式路由通过多个跃点， +并且仅在生产者和最终消费者处实现为本地运行时/语言类型。 +`Timestamp` 类型也可以作为本机协议类型路由， +并且可以在生产者和消费者端映射到/从各自的语言/运行时类型，但永远不会转为字符串格式。 + +序列化机制的选择将决定上下文属性和事件数据将如何序列化。 +例如，在 JSON 序列化的情况下，上下文属性和事件数据可能都出现在同一个 JSON 对象中。 + +### 必要属性 + +下列属性必须自所有的 CloudEvents 中展示： #### id -- Type: `String` -- Description: Identifies the event. Producers MUST ensure that `source` + `id` - is unique for each distinct event. If a duplicate event is re-sent (e.g. due - to a network error) it MAY have the same `id`. Consumers MAY assume that - Events with identical `source` and `id` are duplicates. -- Examples: - - An event counter maintained by the producer - - A UUID -- Constraints: - - REQUIRED - - MUST be a non-empty string - - MUST be unique within the scope of the producer +- 类型: `String` +- 描述: 标识一个事件。 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 + 如果重复的事件被重新发送（例如由于网络错误），它可能具有相同的 `id`。 + Consumers MAY assume that + 消费者可以假设具有相同`source` 和 `id`的事件是重复的。 +- 示例: + - 一个由生产者维护的事件计数器 + - 一个 UUID +- 约束条件: + - 必要的 + - 必须是非空字符串 + - 在生产者的范围内必须是唯一的 #### source -- Type: `URI-reference` -- Description: Identifies the context in which an event happened. Often this - will include information such as the type of the event source, the - organization publishing the event or the process that produced the event. The - exact syntax and semantics behind the data encoded in the URI is defined by - the event producer. - - Producers MUST ensure that `source` + `id` is unique for each distinct event. - - An application MAY assign a unique `source` to each distinct producer, which - makes it easy to produce unique IDs since no other producer will have the same - source. The application MAY use UUIDs, URNs, DNS authorities or an - application-specific scheme to create unique `source` identifiers. - - A source MAY include more than one producer. In that case the producers MUST - collaborate to ensure that `source` + `id` is unique for each distinct event. - -- Constraints: - - REQUIRED - - MUST be a non-empty URI-reference - - An absolute URI is RECOMMENDED -- Examples - - Internet-wide unique URI with a DNS authority. +- 类型: `URI-reference` +- 描述: 标识事件发生的上下文背景。 这通常包括诸如事件源类型、发布事件的组织 + 或产生事件的过程等信息。URI 中编码的数据背后的确切语法和语义由事件生产者定义。 + + 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 + + 应用程序可以为每个不同的生产者分配一个唯一的`source`， + 这使得生成唯一 ID 变得容易，因为没有其他生产者将拥有相同的来源。 + 应用程序可以使用 UUIDs、URNs、DNS权威机构或特定于应用程序的方案来创建唯一的`source` 标识符。 + + 一个来源可以包括多个生产者。 + 在这种情况下，生产者必须协作以确保每个不同事件的 `source` + `id`都是唯一的。 + +- 约束条件: + - 必要的 + - 必须是非空 URI-reference + - 推荐使用 绝对 URI +- 示例 + - 具有 DNS 权限的 Internet 范围唯一 URI： - https://github.com/cloudevents - mailto:cncf-wg-serverless@lists.cncf.io - - Universally-unique URN with a UUID: + - 具有 UUID 的通用唯一 URN： - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 - - Application-specific identifiers + - 应用程序专有的标识符 - /cloudevents/spec/pull/123 - /sensors/tn-1234567/alerts - 1-555-123-4567 #### specversion -- Type: `String` -- Description: The version of the CloudEvents specification which the event - uses. This enables the interpretation of the context. Compliant event - producers MUST use a value of `1.0` when referring to this version of the - specification. -- Constraints: - - REQUIRED - - MUST be a non-empty string +- 类型: `String` +- 描述: 事件使用的 CloudEvents 规范的版本。 + 这让解释上下文环境更容易。 + 当引用这个版本的规范时，兼容的事件生产者必须使用 `1.0` 的值。 +- 约束条件: + - 必要的 + - 必须是非空字符串 #### type -- Type: `String` -- Description: This attribute contains a value describing the type of event - related to the originating occurrence. Often this attribute is used for - routing, observability, policy enforcement, etc. The format of this is - producer defined and might include information such as the version of the - `type` - see - [Versioning of Attributes in the Primer](primer.md#versioning-of-attributes) - for more information. -- Constraints: - - REQUIRED - - MUST be a non-empty string - - SHOULD be prefixed with a reverse-DNS name. The prefixed domain dictates the - organization which defines the semantics of this event type. -- Examples +- 类型: `String` +- 描述: 该属性包含一个值，描述与原始事件相关的事件类型。 + 该属性通常用于路由、可观察性、策略实施等。其格式是生产者定义的，可能包括诸如 `type`版本之类的信息 + -从 + [入门文档-属性版本控制](primer.md#属性版本控制) 中获得更多信息 + +- 约束条件: + - 必要的 + - 必须是非空字符串 + - 应该以反向 DNS 名称作为前缀。该前缀域表明了定义此事件类型语义的组织。 +- 示例 - com.github.pull.create - com.example.object.delete.v2 -### OPTIONAL Attributes +### 可选属性 -The following attributes are OPTIONAL to appear in CloudEvents. See the -[Notational Conventions](#notational-conventions) section for more information -on the definition of OPTIONAL. +下列属性在 CloudEvents 中是可选的. 在 +[符号约定](#notational-conventions) 中查看更多 OPTIONAL 定义的信息。 #### datacontenttype -- Type: `String` per [RFC 2046](https://tools.ietf.org/html/rfc2046) -- Description: Content type of `data` value. This attribute enables `data` to - carry any type of content, whereby format and encoding might differ from that - of the chosen event format. For example, an event rendered using the - [JSON envelope](./json-format.md#3-envelope) format might carry an XML payload - in `data`, and the consumer is informed by this attribute being set to - "application/xml". The rules for how `data` content is rendered for different - `datacontenttype` values are defined in the event format specifications; for - example, the JSON event format defines the relationship in - [section 3.1](./json-format.md#31-handling-of-data). - - For some binary mode protocol bindings, this field is directly mapped to the - respective protocol's content-type metadata property. Normative rules for the - binary mode and the content-type metadata mapping can be found in the - respective protocol - - In some event formats the `datacontenttype` attribute MAY be omitted. For - example, if a JSON format event has no `datacontenttype` attribute, then it is - implied that the `data` is a JSON value conforming to the "application/json" - media type. In other words: a JSON-format event with no `datacontenttype` is - exactly equivalent to one with `datacontenttype="application/json"`. - - When translating an event message with no `datacontenttype` attribute to a - different format or protocol binding, the target `datacontenttype` SHOULD be - set explicitly to the implied `datacontenttype` of the source. - -- Constraints: - - OPTIONAL - - If present, MUST adhere to the format specified in - [RFC 2046](https://tools.ietf.org/html/rfc2046) -- For Media Type examples see +- 类型: `String` [RFC 2046](https://tools.ietf.org/html/rfc2046) +- 描述: `data`值的内容类型。 此属性使`data`能够承载任何类型的内容， + 因此格式和编码可能与所选事件格式的不同。 + 例如，使用 [JSON envelope](./json-format.md#3-envelope) + 格式呈现的事件可能在数据中携带 XML 的payload，这个属性可以用来通知消费者 + 设置"application/xml"。 + 关于`data`内容如何提供不同的`datacontenttype`的值的规则在事件格式规范中定义。 + 例如，JSON 事件格式定义了 [3.1 节](./json-format.md#31-handling-of-data)中的关系。 + 对于某些二进制模式协议绑定， + 此字段直接能映射到相应协议的内容类型的元数据属性上。 + 二进制模式和内容类型元数据映射的规范规则可以在各自的协议中找到。 + + 在某些事件格式中，可以省略 `datacontenttype` 属性。 + 例如，如果 JSON 格式的事件没有 `datacontenttype` 属性， + 则表示该`data`是符合“application/json”媒体类型的 JSON 值。 + 换句话说：一个没有 `datacontenttype` 的 JSON 格式的事件完全等同于 + 一个带有 `datacontenttype="application/json"`的事件。 + + 当将没有 `datacontenttype` 属性的事件消息转换为不同的格式或协议绑定时， + 目标 `datacontenttype` 应该显式设置为事件源的隐含或默认的 `datacontenttype`。 + +- 约束条件: + - 可选的 + - 若有则必须遵守 + [RFC 2046](https://tools.ietf.org/html/rfc2046) 制定的格式 +- 媒体类型示例 [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml) #### dataschema -- Type: `URI` -- Description: Identifies the schema that `data` adheres to. Incompatible - changes to the schema SHOULD be reflected by a different URI. See - [Versioning of Attributes in the Primer](primer.md#versioning-of-attributes) - for more information. -- Constraints: - - OPTIONAL - - If present, MUST be a non-empty URI +- 类型: `URI` +- 描述: 标识 `data` 遵守的规范。 对模式的不兼容的更改应该由不同的 URI 体现。 在 + [入门文档-属性版本控制](primer.md#属性版本控制) + 中查看更多信息。 +- 约束条件: + - 可选的 + - 若有必须是非空的 URI #### subject -- Type: `String` -- Description: This describes the subject of the event in the context of the - event producer (identified by `source`). In publish-subscribe scenarios, a - subscriber will typically subscribe to events emitted by a `source`, but the - `source` identifier alone might not be sufficient as a qualifier for any - specific event if the `source` context has internal sub-structure. - - Identifying the subject of the event in context metadata (opposed to only in - the `data` payload) is particularly helpful in generic subscription filtering - scenarios where middleware is unable to interpret the `data` content. In the - above example, the subscriber might only be interested in blobs with names - ending with '.jpg' or '.jpeg' and the `subject` attribute allows for - constructing a simple and efficient string-suffix filter for that subset of - events. - -- Constraints: - - OPTIONAL - - If present, MUST be a non-empty string -- Example: - - A subscriber might register interest for when new blobs are created inside a - blob-storage container. In this case, the event `source` identifies the - subscription scope (storage container), the `type` identifies the "blob - created" event, and the `id` uniquely identifies the event instance to - distinguish separate occurrences of a same-named blob having been created; - the name of the newly created blob is carried in `subject`: +- 类型: `String` +- 描述: 这个属性描述了事件生产者 (由`source`标识) 上下文环境中的主题信息。 + 在发布-订阅场景中，订阅者通常会订阅`source`发出的事件， + 但如果`source` 的上下文环境具有内部子结构， + 则单独的`source`标识符可能不足以作为任何指定事件的限定符。 + + 在上下文元数据中识别事件的主题（与仅在数据负载中相反） + 对于中间件无法解释`data` 内容的通用订阅过滤场景特别有用。 + 在上面的示例中，订阅者可能只对名称以“.jpg”或“.jpeg”结尾的blob感兴趣， + 此时`subject` 属性允许为该事件子集构建简单有效的字符串后缀过滤器。 + +- 约束条件: + - 可选的 + - 若有必须是非空字符串 +- 示例: + - 订阅者可能对在blob在blob存储容器中创建的时候感兴趣并订阅。 + 在这个场景下，事件`source`标示出订阅的范围（存储容器），`type` 标识出 + blob 创建" 这个事件，`id` 唯一标识出事件示例，以区分已创建同名blob的事件， + 而新创建的blob的名字可以放在`subject`属性中： - `source`: https://example.com/storage/tenant/container - `subject`: mynewfile.jpg #### time -- Type: `Timestamp` -- Description: Timestamp of when the occurrence happened. If the time of the - occurrence cannot be determined then this attribute MAY be set to some other - time (such as the current time) by the CloudEvents producer, however all - producers for the same `source` MUST be consistent in this respect. In other - words, either they all use the actual time of the occurrence or they all use - the same algorithm to determine the value used. -- Constraints: - - OPTIONAL - - If present, MUST adhere to the format specified in +- 类型: `Timestamp` +- 描述: 事件发生的时间戳。 + 如果无法确定发生的时间，则 CloudEvents 生产者可以将此属性设置为其他时间（例如当前时间）。 + 但是在这方面，同一`source`的所有生产者必须保持一致。 + 换句话说，要么它们都使用发生的实际时间，要么它们都使用相同的算法来确定所使用的值。 + +- 约束条件: + - 可选的 + - 若有则必须遵守 [RFC 3339](https://tools.ietf.org/html/rfc3339) -### Extension Context Attributes - -A CloudEvent MAY include any number of additional context attributes with -distinct names, known as "extension attributes". Extension attributes MUST -follow the same [naming convention](#attribute-naming-convention) and use the -same [type system](#type-system) as standard attributes. Extension attributes -have no defined meaning in this specification, they allow external systems to -attach metadata to an event, much like HTTP custom headers. - -Extension attributes are always serialized according to binding rules like -standard attributes. However this specification does not prevent an extension -from copying event attribute values to other parts of a message, in order to -interact with non-CloudEvents systems that also process the message. Extension -specifications that do this SHOULD specify how receivers are to interpret -messages if the copied values differ from the cloud-event serialized values. - -#### Defining Extensions - -See -[CloudEvent Attributes Extensions](primer.md#cloudevent-attribute-extensions) -for additional information concerning the use and definition of extensions. - -The definition of an extension SHOULD fully define all aspects of the -attribute - e.g. its name, type, semantic meaning and possible values. New -extension definitions SHOULD use a name that is descriptive enough to reduce the -chances of name collisions with other extensions. In particular, extension -authors SHOULD check the [documented extensions](documented-extensions.md) -document for the set of known extensions - not just for possible name conflicts -but for extensions that might be of interest. - -Many protocols support the ability for senders to include additional metadata, -for example as HTTP headers. While a CloudEvents receiver is not mandated to -process and pass them along, it is RECOMMENDED that they do so via some -mechanism that makes it clear they are non-CloudEvents metadata. - -Here is an example that illustrates the need for additional attributes. In many -IoT and enterprise use cases, an event could be used in a serverless application -that performs actions across multiple types of events. To support such use -cases, the event producer will need to add additional identity attributes to the -"context attributes" which the event consumers can use to correlate this event -with the other events. If such identity attributes happen to be part of the -event "data", the event producer would also add the identity attributes to the -"context attributes" so that event consumers can easily access this information -without needing to decode and examine the event data. Such identity attributes -can also be used to help intermediate gateways determine how to route the -events. - -## Event Data - -As defined by the term [Data](#data), CloudEvents MAY include domain-specific -information about the occurrence. When present, this information will be -encapsulated within `data`. - -- Description: The event payload. This specification does not place any - restriction on the type of this information. It is encoded into a media format - which is specified by the `datacontenttype` attribute (e.g. application/json), - and adheres to the `dataschema` format when those respective attributes are - present. - -- Constraints: - - OPTIONAL - -# Size Limits - -In many scenarios, CloudEvents will be forwarded through one or more generic -intermediaries, each of which might impose limits on the size of forwarded -events. CloudEvents might also be routed to consumers, like embedded devices, -that are storage or memory-constrained and therefore would struggle with large -singular events. - -The "size" of an event is its wire-size and includes every bit that is -transmitted on the wire for the event: protocol frame-metadata, event metadata, -and event data, based on the chosen event format and the chosen protocol -binding. - -If an application configuration requires for events to be routed across -different protocols or for events to be re-encoded, the least efficient -protocol and encoding used by the application SHOULD be considered for -compliance with these size constraints: - -- Intermediaries MUST forward events of a size of 64 KByte or less. -- Consumers SHOULD accept events of a size of at least 64 KByte. - -In effect, these rules will allow producers to publish events up to 64KB in size -safely. Safely here means that it is generally reasonable to expect the event to -be accepted and retransmitted by all intermediaries. It is in any particular -consumer's control, whether it wants to accept or reject events of that size due -to local considerations. - -Generally, CloudEvents publishers SHOULD keep events compact by avoiding -embedding large data items into event payloads and rather use the event payload -to link to such data items. From an access control perspective, this approach -also allows for a broader distribution of events, because accessing -event-related details through resolving links allows for differentiated access -control and selective disclosure, rather than having sensitive details embedded -in the event directly. - -# Privacy and Security - -Interoperability is the primary driver behind this specification, enabling such -behavior requires some information to be made available _in the clear_ resulting -in the potential for information leakage. - -Consider the following to prevent inadvertent leakage especially when leveraging -3rd party platforms and communication networks: - -- Context Attributes - - Sensitive information SHOULD NOT be carried or represented in context - attributes. - - CloudEvent producers, consumers, and intermediaries MAY introspect and log - context attributes. - -- Data +### 扩展上下文属性 + +CloudEvent 可以包含任意数量的具有不同名称的附加上下文属性，被称为"扩展属性"。 +扩展属性必须遵循相同的[命名约定](#属性命名约定)并使用与标准属性相同的 +[类型系统](#类型系统)。 +扩展属性在本规范中没有定义好的含义， +它们允许外部系统将元数据附加到事件，就像 HTTP 自定义头部一样。 + +扩展属性总是如标准属性一样，根据绑定规则进行序列化。 +然而，该规范不阻止扩展将事件属性值复制到消息的其他部分， +以便与也其它处理消息的非 CloudEvents 系统进行交互。 +如果复制的值与云事件序列化值不同，执行此操作的扩展规范应该指定接收者如何解释消息。 + +#### 定义扩展 + +在 +[CloudEvent-属性扩展](primer.md#CloudEvent-属性扩展) +查阅有关扩展使用和定义等相关信息。 + +扩展的定义应该完全定义属性的方方面面——例如 它的名称、类型、语义含义和可能的值。 +新的扩展定义应该使用一个足够描述性的名称来减少与其他扩展的名称冲突的机会。 +特别是，扩展作者应该检查[扩展文件](documented-extensions.md)中 +已知的扩展集——不仅是可能的名称冲突，还有相同目的冲突的扩展。 + +许多协议为发送者提供了包含额外元数据的能力，例如作为 HTTP 头部。 +虽然没有强制要求 CloudEvents 接受者处理和传递它们， +但建议接受者通过某种机制进行处理，以明确它们是非 CloudEvents 的元数据。 + +下面是一个示例，说明了 CloudEvents 对附加属性的需求。 +在许多物联网和企业用例中，事件可用于跨多种类型事件执行操作的serverless应用程序中。 +为了支持这样的用例，事件生产者需要向“上下文属性”添加额外的身份属性， +事件消费者可以使用这些属性将这个事件与其他事件相关联。 +如果此类身份属性恰好是事件“数据”的一部分， +则事件生产者还会将身份属性添加到“上下文属性”中， +以便事件消费者可以轻松访问此信息，而无需解码和检查事件数据。 +此类身份属性还可用于帮助中间网关确定如何路由事件。 + +## 事件数据 + +正如[数据](#数据)所定义的那样，CloudEvents 可以包括有关事件的特定域的信息。 +这些信息将被封装在`data`中。 + +- 描述: 事件负载。 本规范对该信息的类型不作任何限制。 + 它被编码为一种媒体格式，这种格式由`datacontenttype` 属性(如 application/json)指定， + 并在存在这些相应属性时遵循`dataschema`格式。 + It is encoded into a media format + +- 约束条件: + - 可选的 + +# 大小限制 + +在很多情况下，CloudEvents 将通过一个或多个通用中间人进行转发， +每个中间人都可能对转发事件的大小施加限制。 +CloudEvents 也可能直接被路由到消费者，如嵌入式设备， +这些设备是受存储或内存限制的，对单个大型事件表现不佳。 + +事件的“大小”是它的线路大小，包括在线路上为事件传输的每一位： +协议帧元数据、事件元数据和事件数据，基于所选的事件格式和所选的协议绑定。 + +如果应用程序配置需要跨不同协议路由事件或重新编码事件， +应用程序能使用的效率最低的协议和编码，都修腰符合这些大小限制： + +- 中间人转发的事件大小必须为 64 KB 或更小。 +- 消费者应该能接受大小至少为 64 KB 的事件。 + +为了方便，上述规则将允许生产者安全地发布最大 64KB 的事件。 +这里的安全意味着生产者期望事件被所有中间人接受并合理地转发。 +它是在任何特定消费者的控制之下，无论消费者是否由于本地考虑而选择接受或拒绝该大小的事件。 + +通常，CloudEvents 发布者应该通过避免将大型数据项嵌入到事件而使用事件有效链接到此类数据项， +来保持事件紧凑。 +从访问控制的角度来看，这种方法对更广泛的事件分布式化有帮助， +因为通过解析链接访问与事件相关的细节能实现差异化访问控制和选择性披露， +而不是将敏感详细数据直接嵌入到事件中。 + +# 隐私与安全 + +互操作性是本规范背后的主要驱动力， +实现此目标需要一些信息明确可用，这可能导致信息的泄漏。 + +考虑以下事项以防止信息意外泄漏，尤其是在利用第三方平台和通信网络时： + +- 上下文属性 + + 敏感信息不应在上下文属性中携带。 + + CloudEvent 生产者、消费者和中间人可以自查并记录下上下文属性。 + +- 数据 + + 特定的[事件数据](#事件数据) 应该被加密以限制对受信任方的可见性。 + 用于这种加密的机制是生产者和消费者之间的协议，不在本规范的讨论范围内。 + +- 协议绑定 + 应该采用协议级别的安全性机制来确保 CloudEvents 完成可信和安全的交换。 - Domain specific [event data](#event-data) SHOULD be encrypted to restrict - visibility to trusted parties. The mechanism employed for such encryption is - an agreement between producers and consumers and thus outside the scope of - this specification. - -- Protocol Bindings - - Protocol level security SHOULD be employed to ensure the trusted and secure - exchange of CloudEvents. - -# Example +# 示例 -The following example shows a CloudEvent serialized as JSON: +以下示例展示了一个序列化为 JSON 的 CloudEvent： ```JSON { From 62bc327a98053d6e23d056cf59ee311d7ffcb280 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 14:34:22 +0800 Subject: [PATCH 09/60] Update primer.md --- primer.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/primer.md b/primer.md index 08a69951f..e0d42efef 100644 --- a/primer.md +++ b/primer.md @@ -1,5 +1,10 @@ # CloudEvents 入门文档 - 1.0 版本 +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. + ## 摘要 这份非技术规范文档用来为你提供关于CloudEvents规范的总体概览。它补充了CloudEvents规范的相关背景以及在制定 From 56aaf93d5ccd69c12397627df20b5f33c0b1ad7e Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 14:34:25 +0800 Subject: [PATCH 10/60] Update README.md --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 035a7b928..34db8c3c0 100644 --- a/README.md +++ b/README.md @@ -45,8 +45,9 @@ CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvent | Primer | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/primer.md) | [master](https://github.com/cloudevents/spec/blob/master/primer.md) | | Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | -对于初次接触CloudEvents的同学，建议通过阅读[入门文档](primer.md)增加对CloudEvents规范的目标和设计理念 -的总体理解，然后再继续阅读[核心规范](spec.md)。 +对于初次接触CloudEvents的同学，可以通过阅读[入门文档](primer.md)增加对CloudEvents规范的目标和设计理念 +的总体理解， +希望在最短时间内使用CloudEvents 规范的同学，可以直接阅读[核心规范](spec.md)。 由于并非所有事件生产者都默认生产符合CloudEvents规范的事件，因此可以用[CloudEvents适配器](https://github.com/cloudevents/spec/blob/master/adapters.md) 来将现有的事件与CloudEvents做适配。 From b70872abf9c5c723711ebc9fea4e67589557bf13 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 14:36:12 +0800 Subject: [PATCH 11/60] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 34db8c3c0..57e49fc9e 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvent ## 步骤 -CloudEvents项目 [旨在](primer.md#design-goals)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 +CloudEvents项目 [旨在](primer.md#设计目标)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 的[标准](spec.md)。 为了完成这个目标，这个项目必须描述： @@ -95,7 +95,7 @@ CloudEvents项目 [旨在](primer.md#design-goals)制定一个能够提升不同 会议日期请查看 [CNCF 公开活动日历](https://www.cncf.io/community/calendar/). CloudEvents规范由 -[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless)开发完成。 +[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 开发完成。 这个工作组每周四的上午9点(美国-太平洋时间)通过Zoom开展视频会议。 通过 PC, Mac, Linux, iOS or Android来参加活动: https://zoom.us/my/cncfserverlesswg From 3f26afc80dde68ba362ab8b768c0754e7ef13ebc Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 15:32:15 +0800 Subject: [PATCH 12/60] Update primer.md --- primer.md | 113 +++++++++++++++++++++++++++--------------------------- 1 file changed, 56 insertions(+), 57 deletions(-) diff --git a/primer.md b/primer.md index e0d42efef..a5382f71f 100644 --- a/primer.md +++ b/primer.md @@ -7,9 +7,9 @@ It is strongly recommended to read the English version if you find anything lost ## 摘要 -这份非技术规范文档用来为你提供关于CloudEvents规范的总体概览。它补充了CloudEvents规范的相关背景以及在制定 -本规范时的历史和设计理念。这样，CloudEvents规范就只需要关注Events规范的技术细节，而不用过多地关心 -背景相关内容。 +这份非技术规范文档用来为你提供关于CloudEvents规范的总体概览。它补充了CloudEvents规范的相关背景 +以及在制定 本规范时的历史和设计理念。这样，CloudEvents的核心规范就只需要关注Events规范的技术细节， +而不用过多地关心背景相关内容。 ## 目录 @@ -30,17 +30,17 @@ It is strongly recommended to read the English version if you find anything lost ## 历史 -[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless)是由 CNCF的 +[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 是由 CNCF的 [技术监管委员会](https://github.com/cncf/toc) 成立，用于研究 -Serverless相关技术并为CNCF推荐相关领域的未来发展计划。其中一项建议就是研究创建一种通用事件格式， +Serverless相关技术并为CNCF推荐相关领域的未来发展计划的。工作组其中一项建议就是研究创建一种通用事件格式， 用于提升不同云厂商间函数的可移植性和事件流处理的互操作性。就此，CloudEvents应运而生。 尽管CloudEvents起初是作为Serverless工作组的项目进行的，但随着CloudEvents规范完成它v0.1版本的里程碑， -技术监管委员会批准了CloudEvents工作作为一个新的独立的CNCF沙箱级项目。 +技术监管委员会批准了CloudEvents作为一个新的独立的CNCF沙箱级项目。 ## CloudEvents-概念 -一个[事件](spec.md#event)包含了[事件发生](spec.md#occurrence)的上下文和相关数据。 +一个[事件](spec.md#事件)包含了[事件发生](spec.md#发生)的上下文和相关数据。 事件的相关数据可以用来唯一标识一件事件的发生。 事件代表了已发生的事实，因此它并不包含任何目的地相关信息，但消息能够传达事件内容，从而将事件数据 @@ -67,7 +67,7 @@ arrow pointing to a box representing the action. The arrow is annotated with 事件可以通过各种行业标准协议（如HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或 平台/供应商专有协议（AWS Kinesis、Azure Event Grid）传输。 -一个操作函数能够处理那些定义了行为或影响的事件，这些行为和效果由来自特定来源的特定事件触发而来。 +一个操作函数能够处理那些定义了行为或影响的事件，这些行为和效果由来自特定源的特定事件触发而来。 虽然超出了规范的范围，但生成事件的目的通常是让其他系统能够轻松地对它们无法控制的源中的更改做出反应。 源和操作通常由不同的开发人员构建。 通常，源是托管服务，而操作是serverless函数（如 AWS Lambda 或 Google Cloud Functions）中 @@ -75,7 +75,7 @@ arrow pointing to a box representing the action. The arrow is annotated with ## 设计目标 -CloudEvents 通常用于分布式系统，以允许服务在开发过程中松耦合，独立部署，之后可以连接以创建新的应用程序。 +CloudEvents 通常用于分布式系统，以允许服务在开发过程中松耦合，独立部署，方便之后连接以创建新的应用程序。 CloudEvents 规范的目标是定义允许服务生产或消费事件的事件系统的互操作性， 其中生产者和消费者可以独立开发和部署。 生产者可以在没有消费者监听时就生成事件， @@ -84,21 +84,21 @@ CloudEvents 规范的目标是定义允许服务生产或消费事件的事件 CloudEvents的核心规范中定义了一组称之为属性的元数据， 它们描述了在系统之间传输的事件以及这些元数据片段应如何显示在该消息中。 -这些元数据是，将请求路由到适当组件并帮助该组件正确处理事件，所需的最小信息集。 +这些元数据是，将请求路由到适当组件并帮助该组件正确处理事件所需的最小信息集。 因此，某些事件本身的数据可能会作为 CloudEvent 属性集的一部分而被复制， 但这样做仅是为了能够正确传递和处理消息。那些不用于该目的的数据应放置在事件（数据）本身中。 -此外，本规范中假设协议层所需，用来将消息传递到目标系统的元数据应完全由协议处理， -因此不包含在 CloudEvents 属性中。 有关更多详细信息，请参阅非目标部分。 +此外，本规范中假设协议层所需的用来将消息传递到目标系统的元数据应完全由协议处理， +因此不包含在 CloudEvents 属性中。 有关更多详细信息，请参阅[非目标](#非目标)部分。 除了这些属性的定义之外，规范还描述了关于如何序列化 -不同格式（例如 JSON）和协议（例如 HTTP、AMQP、Kafka）事件。 +不同格式（例如 JSON）和协议（例如 HTTP、AMQP、Kafka）的事件。 -一些协议本身支持将多个事件批处理到单个 API 调用中。 +一些协议本身支持将多个事件批处理到单个 API 的调用中。 为了提升系统间的互操作性，是否以及如何实现批处理将由协议自己决定。 相关详细信息可以在协议绑定或协议规范中找到。 成批的CloudEvents并没有语义，也没有排序。 -[中间人](spec.md#intermediary)可以添加或删除批处理以及将事件分配给不同的批处理。 +[中间人](spec.md#中间人)可以添加或删除批处理以及将事件分配给不同的批处理。 ### 非目标 @@ -110,7 +110,7 @@ CloudEvents的核心规范中定义了一组称之为属性的元数据， - 包含协议级路由信息 - 事件持久化过程 -就连那些刚接触 CloudEvents 概念的人都普遍建议 +就连那些刚接触 CloudEvents 概念的人都会建议 CloudEvents 规范不应包括协议级路由信息（例如，将事件发送到的目标的URL）。 经过深思熟虑，工作组得出的结论是，CloudEvents规范中不需要路由信息： 因为任何现有的协议（例如 HTTP、MQTT、XMPP 或 Pub/Sub 总线）都已经定义了路由语义。 @@ -120,9 +120,9 @@ CloudEvents 不需要在规范中包含目标 URL 即可与 HTTP 兼容；HTTP 路由信息不仅是多余的，而且是有害的。 CloudEvents 应该增加互操作性并解耦事件的生产者和消费者。 -禁止来自事件格式的路由信息允许将 CloudEvents 重新传送到新操作，或通过包含多个通道的复杂中继传送。 +禁止来自事件格式的路由信息允许将 CloudEvents 重新传送到新的行为，或通过包含多个通道的复杂中继传送。 例如，如果 Webhook 地址不可用，则用于 Webhook 的 CloudEvent 应可传送到死信队列。 -死信队列应该能够将事件提供给原始事件发射器从未想象过的新操作。 +死信队列应该能够将事件传送给原始事件发射者从未想象过的新的行为上。 在系统内和跨系统生产和消费的 CloudEvent能够触发产生价值的行为。 因此，对于调试或复制的目的而言，存档和或重放事件可能很有价值。 @@ -137,7 +137,7 @@ CloudEvents 规范集定义了四种有助于形成分层架构模型的不同 1. [基本规范](spec.md) 定义了一个抽象信息模型， 该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 -2. [扩展](./spec.md#extension-context-attributes) +2. [扩展属性](./spec.md#扩展上下文属性) 添加了特定于用例且可能重叠的扩展属性集和相关规则，如支持不同的追踪标准的规则。 3. 事件格式编码,如 [JSON](json-format.md), 定义了基本规范的信息模型与所选扩展的编码方式， 以将其映射到应用程序协议的头部和负载元素。 @@ -180,7 +180,7 @@ CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强 `id` 属性是一个在同一事件源下所有事件中用来标识事件唯一的值 （其中每个事件源由其 CloudEvents `source`属性唯一标识）。 虽然`id`使用的确切值是生产者定义的， -但可以确保来自单个事件源的 CloudEvents 消费者不会有两个事件共享相同的 id 值。 +但必须要确保来自单个事件源的 CloudEvents 消费者不会有两个事件共享相同的 id 值。 唯一的例外是如果支持事件的重播，在这些情况下，可以使用 id 来检测这一点。 由于一次事件的发生可能导致生成多个cloud event， @@ -211,16 +211,16 @@ CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强 “必要”属性是工作组认为在任何情况下，对所有事件都至关重要的属性， 而“可选”属性将在大多数情况下使用。 这些情况下的两个属性都在本规范中定义了出来。 -当工作组考虑到某些属性不够常见而不能归入上述两个类别， +工作组考虑到某些属性不够常见而不能归入上述两个类别， 但此类属性的良好定义仍会使系统间的互操作性级别受益， -则将这些属性放入了“扩展”类别并记录在[扩展文档](documented-extensions.md)中， +因此将这些属性放入了“扩展”类别并记录在[扩展文档](documented-extensions.md)中， 本规范定义了这些扩展属性在 CloudEvent 中的显示方式。 在确定提议的属性属于哪个类别时， 工作组使用现有的用例和用户故事来解释它们的基本原理和需求。 -相关信息将添加到本文档的[现有技术](#prior-art)部分。 +相关信息将添加到本文档的[现有技术](#现有技术)部分。 -CloudEvent 规范的扩展属性是需要包含的附加元数据，它们能确保合适的路由和正确处理CloudEvent。 +CloudEvent 规范的扩展属性是需要包含的附加元数据，它们能确保正确的路由和正确处理CloudEvent。 用于其它目的的附加元数据， 即那些与事件本身相但在 CloudEvent 的传输或处理中不需要的元数据， 应改为放置在事件 (`data`)的扩展点内。 @@ -244,12 +244,12 @@ CloudEvent 扩展属性与已定义属性(必要属性、可选属性)在序列 CloudEvent的作者花了很长时间考虑所有选项，并认为这是最好的选择。 理由如下： -由于CloudEvents规范遵循 [semver](https://semver.org/)， -这意味着只要新属性是可选属性，它们可以由核心规范的未来版本定义，而无需更改主要版本。 -在这些情况下，请考虑现有消费者将如何使用新的（未知）顶级属性。 +由于CloudEvents规范遵循 [semver](https://semver.org/) ， +这意味着只要新属性是可选属性，它们可以在核心规范的未来版本定义，而无需更改当前主要版本。 +在这样的情况下，请考虑现有消费者将如何使用新的（未知的）顶级属性。 虽然消费者可以随意忽略它，因为它是可选的， -但在大多数情况下，这些属性仍然希望向接收这些事件的应用公开。 -这将允许这些应用程序支持这些属性，即使基础设施不支持。 +但在大多数情况下，这些属性仍然希望向接收这些事件的应用程序公开。 +这可能导致这些应用程序在基础设施不支持的情况下，支持这些属性。 这意味着未知的顶级属性（无论是谁定义的——规范的未来版本或事件生产者）可能不会被忽略。 因此，虽然其它一些规范定义了放置扩展的特定属性（例如顶级`extensions`属性）， 但作者认为在传入事件中具有两个不同位置的未知属性可能会导致互操作性问题和开发人员的混淆。 @@ -259,20 +259,20 @@ CloudEvent的作者花了很长时间考虑所有选项，并认为这是最好 那么如果该属性被核心规范采用，它将从`extensions`属性提升（从序列化的角度）为顶级属性。 如果我们假设这个新属性是可选的，那么当它被核心规范采用时， 它只是一个小版本增量，所有现有的消费者仍然会继续工作。 -但是，消费者将不知道此属性将出现在何处 - 在扩展属性中或是作为顶级属性。 +但是，消费者将不知道此属性将出现在何处 - 在扩展属性中还是作为顶级属性。 这意味着他们可能需要同时查看两个地方。 如果属性出现在两个地方但具有不同的值怎么办？ -生产者是否需要将它放在两个地方，因为他们可能有新老消费者？ -虽然有可能为如何解决出现的每个潜在问题定义明确的规则， +生产者是否需要将它放在两个地方，因为他们可能同时有新、老消费者？ +虽然可以为如何解决出现的每个潜在问题而制定明确的规则， 但作者认为一个避免这些问题的更好的办法是在序列化中只有一个位置来放置未知的甚至是新的属性。 作者还注意到 HTTP 规范现在遵循类似的模式，不再建议扩展 HTTP 头部以 X- 为前缀。 ## 生产CloudEvents CloudEvents 规范有意避免将CloudEvents 的创建方式设计的过于死板。 -例如，它不假定原始事件源必须是该事件构造关联 CloudEvent 的同一实体。 +例如，它不假定原始事件源必须是该事件生产对应 CloudEvent 的同一实体。 这允许多种实现方式。 -但是，对于规范的实现者来说，理解规范作者心中的期望是很有用的，因为这将有助于确保互操作性和一致性。 +但是，对于规范的实现者来说，理解规范作者心中的期望还是有帮助的，因为这将有助于确保互操作性和一致性。 如上所述，生成初始事件的实体是否与创建相应 CloudEvent 的实体相同是由实现决定的。 但是，当构建/填充 CloudEvents 属性的实体代表事件源进行操作时，这些属性的值是用来描述事件或事件源， @@ -298,7 +298,7 @@ CloudEvents 规范有意避免将CloudEvents 的创建方式设计的过于死 但是，如果此实体正在执行 CloudEvent 的某种类型的语义处理， 通常会导致`data`属性值发生更改， 则可能需要将其视为与原始事件源不同的“事件源”。 -因此，预计与事件生产者相关的 CloudEvents 属性（例如`source` and `id`） +因此，与事件生产者相关的 CloudEvents 属性（例如`source` and `id`） 将从传入的 CloudEvent 中更改。 ## 合格的协议与编码 @@ -317,7 +317,7 @@ CloudEvents 旨在提供这种开放的数据格式，并将其数据格式映 例如 HTTP 1.1 和 HTTP/2 以及 WebSockets 或 Web 上的事件，或者 MQTT 和 AMQP 用于面向连接的消息传递和遥测传输的协议。 -一些广泛使用的协议已经成为事实上的标准，这些协议来自三个或更多公司的顶级财团的强大生态系统， +一些广泛使用的协议已经成为事实上的标准，这些协议来自三个或更多公司的顶级财团打造的强大生态系统， 还有一些来自单个公司发布的强大项目生态系统，在任何一种情况下都与前面提到的标准栈的演变相一致。 CloudEvents的努力不应成为认可或推广项目或产品专有协议的工具， @@ -337,14 +337,14 @@ CloudEvents的努力不应成为认可或推广项目或产品专有协议的工 对此的基本要求是协议或编码的定义方式允许独立于产品或项目代码的替代实现。 欢迎将 CloudEvents 的所有其他协议和编码格式 -包含在指向相应项目自己的公共存储库或站点中的 CloudEvents binding信息的列表中。 +包含在指向相应项目自己的公共仓库，或站点中的 CloudEvents binding信息的列表中。 ## 专有的协议与编码 为了鼓励更多人采用 CloudEvents，本仓库将自动收集专有协议和编码。 本仓库的维护人员不负责创建、维护或通知专有规范的维护人员有关专有规范和CloudEvents规范间的偏差。 -专有规范将托管在他们自己的仓库或文档站点中，并收集在[专有规范](proprietary-specs.md) +专有规范将托管在他们自己的仓库或文档站点中，并记录在[专有规范](proprietary-specs.md) 文件中。 专有规范应遵循与核心协议和编码相关的其他规范相同的格式。 专有规范将比核心规范受到更少的审查，并且随着 CloudEvents 规范的发展， @@ -362,7 +362,7 @@ CloudEvents的努力不应成为认可或推广项目或产品专有协议的工 下面列举了可能涉及事件的产生、管理或消费的各种参与者和场景。 在这些中，事件生产者和事件消费者的角色是不同的。 -单个应用程序上下文始终可以同时承担多个角色，包括既是事件的生产者又是事件的消费者。 +单个应用程序上下文背景始终可以同时承担多个角色，包括既是事件的生产者又是事件的消费者。 1. 应用程序生成供他人使用的事件， 如为消费者提供有关终端用户活动、状态变化或环境观察的见解， @@ -378,7 +378,7 @@ CloudEvents的努力不应成为认可或推广项目或产品专有协议的工 作为后者的示例，请考虑设备通过负载大小受限的网络（如 LoRaWAN 或 ModBus）传输的事件数据， 并且符合此规范的事件将由网络网关代表生产者提供。 - 例如，气象站每 5 分钟通过 LoRaWAN 传输一次 12 字节的专有事件有效载荷用于指示天气状况。 + 例如，气象站每 5 分钟通过 LoRaWAN 传输一次 12 字节的专有事件payload用于指示天气状况。 然后使用 LoRaWAN 网关以 CloudEvents 格式将事件发布到 Internet 目标。 LoRaWAN 网关是事件生产者，代表气象站发布事件，并将设置一定的元数据以反映事件的来源(气象站)。 @@ -400,18 +400,17 @@ CloudEvents的努力不应成为认可或推广项目或产品专有协议的工 - 从原始上下文中获取有关事件主题的更多详细信息，例如获取有关需要特权访问授权的已更改对象的详细信息。 例如，出于隐私原因，HR 解决方案可能仅在事件中发布非常有限的信息， - 任何需要更多数据的事件消费者都必须在其自己的授权上下文下从 HR 系统获取与事件相关的详细信息 + 任何需要更多数据的事件消费者都必须在其自己的授权上下文背景下从 HR 系统获取与事件相关的详细信息 - 在原始上下文中与事件的主题进行交互，例如在被告知该数据块刚刚创建后读取存储该数据块。 消费者的兴趣激发了信息生产者应该包括事件的需求。 3. 中间件将事件从生产者路由到消费者，或转发到其他中间件。 - 产生事件的应用程序可能会将消费者需求产生的某些任务委托给中间件： + 产生事件的应用程序可能会将根据消费者需求产生的某些任务委托给中间件： - - Management of many concurrent interested consumers for one of multiple - classes or originating contexts of events + - 管理同时对大量类别和上下文背景中的某个事件感兴趣的消费者。 - 代表消费者在类或事件的原始上下文上处理过滤条件。 - - 转码，比如从 JSON 解码后在 MsgPack 中编码 + - 转码，比如从 JSON 解码后在 MsgPack 中编码。 - 更改事件结构的转换，例如从专有格式映射到 CloudEvents，同时保留事件的身份和语义完整性。 - 即时“推送式”传输给感兴趣的消费者。 - 存储最终传输的事件，用于由消费者发起的“拉”请求，或延迟后由中间件发起“推”请求。 @@ -422,24 +421,24 @@ CloudEvents的努力不应成为认可或推广项目或产品专有协议的工 - 一种元数据鉴别器，可用于事件的分类或上下文化，以便消费者可以表达对一个或多个类或上下文的兴趣。 例如，消费者可能对文件存储帐户内的特定目录相关的所有事件感兴趣。 - 一种元数据鉴别器，允许区分该类或上下文的特定事件的主题。例如，消费者可能希望过滤掉与以“.jpg”结尾的 - 新文件相关的所有事件（文件名是“新文件”事件的主题）， - 用于描述其已注册的文件存储帐户内的特定目录的上下文兴趣。 + 新文件相关的所有事件（文件名是“新文件”事件的主题），以此表示它对感兴趣的文件存储账户下某个目录的 + 上下文环境。 - 一个事件及其数据编码的指示器。 - 一个事件及其数据的结构布局（模式）的指示器。 事件是否可通过中间件消费取决于生产者的选择。 - 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec.md#producer)的角色， - 当它根据事件采取行动时可以扮演[消费者](spec.md#consumer)的角色， - 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec.md#intermediary)的角色。 + 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec.md#生产者)的角色， + 当它根据事件采取行动时可以扮演[消费者](spec.md#消费者)的角色， + 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec.md#中间人)的角色。 -4. 框架和其他抽象使与事件平台基础设施的交互更简单， +4. 框架和其他抽象使与事件平台基础设施间的交互更简单， 并且通常为多个事件平台基础设施提供公共 API 区域。 - 框架通常用于将事件转换为对象图，并将事件分派给某些特定的处理用户代码或用户规则， - 这些用户代码或用户规则允许消费应用程序对原始上下文和特定主题中的特定类型的事件做出反应。 + 框架通常用于将事件转换为对象图，并将事件分派给某些特定的处理逻辑或用户规则， + 这些用户逻辑或用户规则允许消费应用程序对原始上下文和特定主题中的特定类型的事件做出反应。 - 框架最感兴趣的是跨它们抽象的平台的语义元数据通用性，以便可以统一处理类似的活动。 + 框架最感兴趣的是跨抽象平台的语义元数据通用性，以便可以统一处理类似的活动。 对于体育应用程序，使用该框架的开发人员可能对联盟中一支球队今天的比赛（主题） 的所有事件感兴趣，但希望以不同于“换人”事件的方式处理“得分”事件。 @@ -487,7 +486,7 @@ CloudEvents 可以提供更好的开发工具来构建、测试和处理事件 大多数平台和服务对其事件的数据模型进行不同的版本控制（如果他们这样做的话）。 随着这些数据模型的发展，这会为发布和使用事件的数据模型带来不一致的体验。 -CloudEvents 可以提供一种通用的方式来版本化和发展事件数据。 +CloudEvents 可以提供一种通用的方式来版本化和演化事件数据的发展。 这将帮助事件发布者根据最佳实践安全地对其数据模型进行版本控制， 并且这有助于事件消费者随着事件数据的发展安全地使用它。 @@ -507,8 +506,8 @@ CloudEvents 可以提供 Webhook 发布和消费事件的一致性。 #### 事件追踪 -从源发送的事件可能会出现在一系列附加事件之间， -这些附加事件从各种中间件设备（例如事件代理和网关）发出的。 +从源发送的事件可能会出现在一系列附加事件序列之中， +这些附加事件序列从各种中间件设备（例如事件代理和网关）发出。 CloudEvents 在事件中包含元数据以将这些事件关联为事件序列的一部分，以便进行事件跟踪和故障排除。 #### IoT From c74546e0d24456248fc103f5bd164f51ca95ad4a Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 15:40:21 +0800 Subject: [PATCH 13/60] Update spec.md --- spec.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/spec.md b/spec.md index 1f1428ec8..7c9c1a8cd 100644 --- a/spec.md +++ b/spec.md @@ -1,10 +1,13 @@ # CloudEvents 核心规范- 1.0 版本 +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. + ## 摘要 CloudEvents 是一个用于定义事件格式的供应商中立规范。 -CloudEvents is a vendor-neutral specification for defining the format of event -data. ## 目录 @@ -64,7 +67,7 @@ CloudEvents是一个以通用格式来描述事件数据的标准。它提供了 #### 事件 -“事件”是表示"发生"及其上下文的数据记录。 +“事件”是表示一条"发生"及其上下文的数据记录。 事件从事件生产者（源）路由到对它感兴趣的事件消费者。 事件中包含的信息帮助完成路由操作，但事件不会标识特定的路由目的地。 事件将包含两种类型的信息：表示"发生"的 [事件数据](#事件数据) @@ -89,7 +92,7 @@ CloudEvents是一个以通用格式来描述事件数据的标准。它提供了 一个“中间人”会接收包含事件的消息， 并将其转发给下一个接收者，但该接收者可能是另一个中间人或事件[消费者](#消费者)。 -中间人的典型任务就是根据[上下文](#context)环境中的信息将事件路由到接收者。 +中间人的典型任务就是根据[上下文](#上下文)环境中的信息将事件路由到接收者。 #### 上下文 @@ -113,7 +116,7 @@ CloudEvents是一个以通用格式来描述事件数据的标准。它提供了 “结构化模式消息”是一种使用独立事件格式对事件进行完全编码并存储在消息体中的消息。 -“二进制模式消息”是将事件数据存储在消息体中，并将事件属性作为消息元数据的一部分存储下来。 +“二进制模式消息”会将事件数据存储在消息体中，并将事件属性作为消息元数据的一部分存储下来。 #### 协议 @@ -136,7 +139,7 @@ CloudEvents是一个以通用格式来描述事件数据的标准。它提供了 ### 属性命名约定 -CloudEvents 规范定义了到各种协议和编码的映射，随附的 CloudEvents SDK 面向各种运行时和语言。 +CloudEvents 规范定义了到各种协议和编码的映射，随附的 CloudEvents SDK 面向各种运行时和编程语言。 其中一些将元数据元素区分大小写，而另一些则不区分， 并且单个 CloudEvent 可能通过涉及到协议、编码和运行时混合的多个跃点进行路由。 因此，本规范限制了所有属性的可用字符集，以防止区分大小写问题或与通用语言中标识符的合法字符集冲突问题。 From 28811a0ca162d4559775d60b61f852a5798fca2c Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:23:09 +0800 Subject: [PATCH 14/60] Create README_CN.md --- README_CN.md | 132 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 README_CN.md diff --git a/README_CN.md b/README_CN.md new file mode 100644 index 000000000..57e49fc9e --- /dev/null +++ b/README_CN.md @@ -0,0 +1,132 @@ +# CloudEvents Chinese Manual + +![CloudEvents logo](https://github.com/cncf/artwork/blob/master/projects/cloudevents/horizontal/color/cloudevents-horizontal-color.png) + +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. + +事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 + +对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。它同样限制了那些用来帮助事件数据完成 +跨环境传输的库(如SDKs)，工具(如事件路由器)和基础设施(如事件追踪系统)的发展。总体来看，这种匮乏严重阻碍了事件数据的 +可移植性和生产力。 + +CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 + +CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvents被[云原生计算基金会](https://cncf.io) (CNCF)持有， +在[2018/05/15](https://docs.google.com/presentation/d/1KNSv70fyTfSqUerCnccV7eEC_ynhLsm9A_kjnlmU_t0/edit#slide=id.g37acf52904_1_41) +被选为云原生沙箱级项目。 + +## CloudEvents 文件 + +现有文件如下: + +| | 最新版本 | 工作草稿 | +| :---------------------------- | :----------------------------------------------------------------------------: | :---------------------------------------------------------------------------------: | +| **核心标准:** | +| CloudEvents | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/spec.md) | [master](https://github.com/cloudevents/spec/blob/master/spec.md) | +| | +| **可选标准:** | +| AMQP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/amqp-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-protocol-binding.md) | +| AVRO Event Format | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/avro-format.md) | [master](https://github.com/cloudevents/spec/blob/master/avro-format.md) | +| HTTP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/http-protocol-binding.md) | +| JSON Event Format | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/json-format.md) | [master](https://github.com/cloudevents/spec/blob/master/json-format.md) | +| Kafka Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/kafka-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/kafka-protocol-binding.md) | +| MQTT Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/mqtt-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/mqtt-protocol-binding.md) | +| NATS Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/nats-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/nats-protocol-binding.md) | +| Web hook | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md) | [master](https://github.com/cloudevents/spec/blob/master/http-webhook.md) | +| | +| **附加文件:** | +| CloudEvents Adapters | - | [master](https://github.com/cloudevents/spec/blob/master/adapters.md) | +| CloudEvents SDK Requirements | - | [master](https://github.com/cloudevents/spec/blob/master/SDK.md) | +| Documented Extensions | - | [master](https://github.com/cloudevents/spec/blob/master/documented-extensions.md) | +| Primer | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/primer.md) | [master](https://github.com/cloudevents/spec/blob/master/primer.md) | +| Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | + +对于初次接触CloudEvents的同学，可以通过阅读[入门文档](primer.md)增加对CloudEvents规范的目标和设计理念 +的总体理解， +希望在最短时间内使用CloudEvents 规范的同学，可以直接阅读[核心规范](spec.md)。 + +由于并非所有事件生产者都默认生产符合CloudEvents规范的事件，因此可以用[CloudEvents适配器](https://github.com/cloudevents/spec/blob/master/adapters.md) +来将现有的事件与CloudEvents做适配。 + +## SDKs + +除了上述文档，我们还提供了[SDK 提议](SDK.md)以及一些编程语言的SDK： + +- [CSharp](https://github.com/cloudevents/sdk-csharp) +- [Go](https://github.com/cloudevents/sdk-go) +- [Java](https://github.com/cloudevents/sdk-java) +- [Javascript](https://github.com/cloudevents/sdk-javascript) +- [Python](https://github.com/cloudevents/sdk-python) + +## 社区 + +在社区里，你可以了解到更多致力于搭建一个动态、云原生的生态系统的成员和组织。 +他们不断尝试提升现有系统和CloudEvents间的互操作性和兼容性。 + +- [贡献者](community/contributors.md): + 是指那些帮助我们制定规范或是积极活跃在CloudEvents规范相关工作的成员和组织。 +- 即将推出: [demos & open source](community/README.md) -- + 如果你希望向我们分享关于你对CloudEvents的使用，请通过提交PR让我们看到。 + +## 步骤 + +CloudEvents项目 [旨在](primer.md#设计目标)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 +的[标准](spec.md)。 + +为了完成这个目标，这个项目必须描述： + +- 一系列能够提升互操作性的用来描述事件的属性 +- 一个或多个通用架构，这些架构必须是当下活跃的或是正在计划被完成的 +- 事件是如何在一种或多种协议下从生产者传输到消费者的 +- 识别并解决任何能提升互操作性的问题 +## 联系方式 + +邮件联系方式如下: + +- 发送EMail至: [cncf-cloudevents](mailto:cncf-cloudevents@lists.cncf.io) +- 订阅地址: https://lists.cncf.io/g/cncf-cloudevents +- 存档地址: https://lists.cncf.io/g/cncf-cloudevents/topics + +## 会议时间 + +会议日期请查看 [CNCF 公开活动日历](https://www.cncf.io/community/calendar/). +CloudEvents规范由 +[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 开发完成。 +这个工作组每周四的上午9点(美国-太平洋时间)通过Zoom开展视频会议。 +通过 PC, Mac, Linux, iOS or Android来参加活动: https://zoom.us/my/cncfserverlesswg + +或者通过 iPhone one-tap : + + US: +16465588656,,3361029682# or +16699006833,,3361029682# + +或者电话接入: + + Dial: + US: +1 646 558 8656 (US Toll) or +1 669 900 6833 (US Toll) + or +1 855 880 1246 (Toll Free) or +1 877 369 0926 (Toll Free) + +会议 ID: 336 102 9682 + +国际号码接入: +https://zoom.us/zoomconference?m=QpOqQYfTzY_Gbj9_8jPtsplp1pnVUKDr + +世界时区转化器: +http://www.thetimezoneconverter.com/?t=9:00%20am&tz=San%20Francisco& + +## 会议记录 + +历史会议记录在 +[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) +查看。 + +历史会议录像在 +[这里](https://www.youtube.com/playlist?list=PLj6h78yzYM2Ph7YoBIgsZNW_RGJvNlFOt) +查看。 + +工作组会定期举办与主流会议一致的线下会议。查看[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) +了解更多未来计划。 + From 46657ad9b9b12b186416a593e9a02318ecab83d3 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:23:42 +0800 Subject: [PATCH 15/60] Update README_CN.md --- README_CN.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README_CN.md b/README_CN.md index 57e49fc9e..d918be3d4 100644 --- a/README_CN.md +++ b/README_CN.md @@ -1,4 +1,4 @@ -# CloudEvents Chinese Manual +# CloudEvents 中文首层 ![CloudEvents logo](https://github.com/cncf/artwork/blob/master/projects/cloudevents/horizontal/color/cloudevents-horizontal-color.png) From 8c7db53b0952e01386ca2bdad103d14ccd6057e2 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:23:55 +0800 Subject: [PATCH 16/60] Update README_CN.md --- README_CN.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README_CN.md b/README_CN.md index d918be3d4..64a4ee4f7 100644 --- a/README_CN.md +++ b/README_CN.md @@ -1,4 +1,4 @@ -# CloudEvents 中文首层 +# CloudEvents 中文手册 ![CloudEvents logo](https://github.com/cncf/artwork/blob/master/projects/cloudevents/horizontal/color/cloudevents-horizontal-color.png) From b17185d61d3a033e0c3fcc13ad28ca019e9dfce0 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:25:50 +0800 Subject: [PATCH 17/60] Update README.md --- README.md | 146 +++++++++++++++++++++++++++++------------------------- 1 file changed, 79 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 57e49fc9e..c26f0b7df 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,35 @@ -# CloudEvents Chinese Manual +# CloudEvents ![CloudEvents logo](https://github.com/cncf/artwork/blob/master/projects/cloudevents/horizontal/color/cloudevents-horizontal-color.png) -Declaration： This manual aims to provide a fast and brief introduction of CloudEvents -in Chinese for people who are new to CloudEvents. -Most of the content is translated from the original English version. -It is strongly recommended to read the English version if you find anything lost in translation. +Events are everywhere. However, event producers tend to describe events +differently. -事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 +The lack of a common way of describing events means developers must constantly +re-learn how to consume events. This also limits the potential for libraries, +tooling and infrastructure to aide the delivery of event data across +environments, like SDKs, event routers or tracing systems. The portability and +productivity we can achieve from event data is hindered overall. -对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。它同样限制了那些用来帮助事件数据完成 -跨环境传输的库(如SDKs)，工具(如事件路由器)和基础设施(如事件追踪系统)的发展。总体来看，这种匮乏严重阻碍了事件数据的 -可移植性和生产力。 +CloudEvents is a specification for describing event data in common formats to +provide interoperability across services, platforms and systems. -CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 +CloudEvents has received a large amount of industry interest, ranging from major +cloud providers to popular SaaS companies. CloudEvents is hosted by the +[Cloud Native Computing Foundation](https://cncf.io) (CNCF) and was approved as +a Cloud Native sandbox level project on +[May 15, 2018](https://docs.google.com/presentation/d/1KNSv70fyTfSqUerCnccV7eEC_ynhLsm9A_kjnlmU_t0/edit#slide=id.g37acf52904_1_41). -CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvents被[云原生计算基金会](https://cncf.io) (CNCF)持有， -在[2018/05/15](https://docs.google.com/presentation/d/1KNSv70fyTfSqUerCnccV7eEC_ynhLsm9A_kjnlmU_t0/edit#slide=id.g37acf52904_1_41) -被选为云原生沙箱级项目。 +## CloudEvents Documents -## CloudEvents 文件 +The following documents are available: -现有文件如下: - -| | 最新版本 | 工作草稿 | +| | Latest Release | Working Draft | | :---------------------------- | :----------------------------------------------------------------------------: | :---------------------------------------------------------------------------------: | -| **核心标准:** | +| **Core Specification:** | | CloudEvents | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/spec.md) | [master](https://github.com/cloudevents/spec/blob/master/spec.md) | | | -| **可选标准:** | +| **Optional Specifications:** | | AMQP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/amqp-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-protocol-binding.md) | | AVRO Event Format | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/avro-format.md) | [master](https://github.com/cloudevents/spec/blob/master/avro-format.md) | | HTTP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/http-protocol-binding.md) | @@ -38,23 +39,26 @@ CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvent | NATS Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/nats-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/nats-protocol-binding.md) | | Web hook | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md) | [master](https://github.com/cloudevents/spec/blob/master/http-webhook.md) | | | -| **附加文件:** | +| **Additional Documentation:** | | CloudEvents Adapters | - | [master](https://github.com/cloudevents/spec/blob/master/adapters.md) | | CloudEvents SDK Requirements | - | [master](https://github.com/cloudevents/spec/blob/master/SDK.md) | | Documented Extensions | - | [master](https://github.com/cloudevents/spec/blob/master/documented-extensions.md) | | Primer | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/primer.md) | [master](https://github.com/cloudevents/spec/blob/master/primer.md) | | Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | -对于初次接触CloudEvents的同学，可以通过阅读[入门文档](primer.md)增加对CloudEvents规范的目标和设计理念 -的总体理解， -希望在最短时间内使用CloudEvents 规范的同学，可以直接阅读[核心规范](spec.md)。 +If you are new to CloudEvents, it is recommended that you start by reading the +[Primer](primer.md) for an overview of the specification's goals and design +decisions, and then move on to the [core specification](spec.md). -由于并非所有事件生产者都默认生产符合CloudEvents规范的事件，因此可以用[CloudEvents适配器](https://github.com/cloudevents/spec/blob/master/adapters.md) -来将现有的事件与CloudEvents做适配。 +Since not all event producers generate CloudEvents by default, there is +documentation describing the recommended process for adapting some popular +events into CloudEvents, see +[CloudEvents Adapters](https://github.com/cloudevents/spec/blob/master/adapters.md). ## SDKs -除了上述文档，我们还提供了[SDK 提议](SDK.md)以及一些编程语言的SDK： +In addition to the documentation mentioned above, there are also an +[SDK proposal](SDK.md) and a set of SDKs being developed: - [CSharp](https://github.com/cloudevents/sdk-csharp) - [Go](https://github.com/cloudevents/sdk-go) @@ -62,71 +66,79 @@ CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvent - [Javascript](https://github.com/cloudevents/sdk-javascript) - [Python](https://github.com/cloudevents/sdk-python) -## 社区 +## Community + +Learn more about the people and organizations who are creating a dynamic cloud +native ecosystem by making our systems interoperable with CloudEvents. + +- [Contributors](community/contributors.md): people and organizations who helped + us get started or are actively working on the CloudEvents specification. +- Coming soon: [demos & open source](community/README.md) -- if you have + something to share about your use of CloudEvents, please submit a PR! -在社区里，你可以了解到更多致力于搭建一个动态、云原生的生态系统的成员和组织。 -他们不断尝试提升现有系统和CloudEvents间的互操作性和兼容性。 +## Process -- [贡献者](community/contributors.md): - 是指那些帮助我们制定规范或是积极活跃在CloudEvents规范相关工作的成员和组织。 -- 即将推出: [demos & open source](community/README.md) -- - 如果你希望向我们分享关于你对CloudEvents的使用，请通过提交PR让我们看到。 +The CloudEvents project is working to formalize the [specification](spec.md) +based on [design goals](primer.md#design-goals) which focus on interoperability +between systems which generate and respond to events. -## 步骤 +In order to achieve these goals, the project must describe: -CloudEvents项目 [旨在](primer.md#设计目标)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 -的[标准](spec.md)。 +- Common attributes of an _event_ that facilitate interoperability +- One or more common architectures that are in active use today or planned to be + built by its members +- How events are transported from producer to consumer via at least one protocol +- Identify and resolve whatever else is needed for interoperability -为了完成这个目标，这个项目必须描述： +## Communications -- 一系列能够提升互操作性的用来描述事件的属性 -- 一个或多个通用架构，这些架构必须是当下活跃的或是正在计划被完成的 -- 事件是如何在一种或多种协议下从生产者传输到消费者的 -- 识别并解决任何能提升互操作性的问题 -## 联系方式 +The mailing list for e-mail communications: -邮件联系方式如下: +- Send emails to: [cncf-cloudevents](mailto:cncf-cloudevents@lists.cncf.io) +- To subscribe see: https://lists.cncf.io/g/cncf-cloudevents +- Archives are at: https://lists.cncf.io/g/cncf-cloudevents/topics -- 发送EMail至: [cncf-cloudevents](mailto:cncf-cloudevents@lists.cncf.io) -- 订阅地址: https://lists.cncf.io/g/cncf-cloudevents -- 存档地址: https://lists.cncf.io/g/cncf-cloudevents/topics +And a #cloudevents Slack channel under +[CNCF's Slack workspace](https://slack.cncf.io/). -## 会议时间 +## Meeting Time -会议日期请查看 [CNCF 公开活动日历](https://www.cncf.io/community/calendar/). -CloudEvents规范由 -[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 开发完成。 -这个工作组每周四的上午9点(美国-太平洋时间)通过Zoom开展视频会议。 -通过 PC, Mac, Linux, iOS or Android来参加活动: https://zoom.us/my/cncfserverlesswg +See the [CNCF public events calendar](https://www.cncf.io/community/calendar/). +This specification is being developed by the +[CNCF Serverless Working Group](https://github.com/cncf/wg-serverless). This +working group meets every Thursday at 9AM PT (USA Pacific): -或者通过 iPhone one-tap : +Join from PC, Mac, Linux, iOS or Android: https://zoom.us/my/cncfserverlesswg + +Or iPhone one-tap : US: +16465588656,,3361029682# or +16699006833,,3361029682# -或者电话接入: +Or Telephone: Dial: US: +1 646 558 8656 (US Toll) or +1 669 900 6833 (US Toll) or +1 855 880 1246 (Toll Free) or +1 877 369 0926 (Toll Free) -会议 ID: 336 102 9682 +Meeting ID: 336 102 9682 -国际号码接入: +International numbers available: https://zoom.us/zoomconference?m=QpOqQYfTzY_Gbj9_8jPtsplp1pnVUKDr -世界时区转化器: -http://www.thetimezoneconverter.com/?t=9:00%20am&tz=San%20Francisco& +NOTE: Please use \*6 to mute/un-mute your phone during the call. -## 会议记录 +World Time Zone Converter: +http://www.thetimezoneconverter.com/?t=9:00%20am&tz=San%20Francisco& -历史会议记录在 -[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) -查看。 +## Meeting Minutes -历史会议录像在 -[这里](https://www.youtube.com/playlist?list=PLj6h78yzYM2Ph7YoBIgsZNW_RGJvNlFOt) -查看。 +The minutes from our calls are available +[here](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#). -工作组会定期举办与主流会议一致的线下会议。查看[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) -了解更多未来计划。 +Recording from our calls are available +[here](https://www.youtube.com/playlist?list=PLj6h78yzYM2Ph7YoBIgsZNW_RGJvNlFOt). +Periodically, the group may have in-person meetings that coincide with a major +conference. Please see the +[meeting minutes](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) +for any future plans. From 4560ffb3d35f7d998f987befc727be6986f84fc5 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:26:48 +0800 Subject: [PATCH 18/60] Create primer_CN.md --- primer_CN.md | 704 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 704 insertions(+) create mode 100644 primer_CN.md diff --git a/primer_CN.md b/primer_CN.md new file mode 100644 index 000000000..a5382f71f --- /dev/null +++ b/primer_CN.md @@ -0,0 +1,704 @@ +# CloudEvents 入门文档 - 1.0 版本 + +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. + +## 摘要 + +这份非技术规范文档用来为你提供关于CloudEvents规范的总体概览。它补充了CloudEvents规范的相关背景 +以及在制定 本规范时的历史和设计理念。这样，CloudEvents的核心规范就只需要关注Events规范的技术细节， +而不用过多地关心背景相关内容。 + +## 目录 + +- [历史](#历史) +- [CloudEvents 概念](#CloudEvents-概念) +- [设计目标](#设计目标) +- [架构](#架构) +- [属性版本控制](#属性版本控制) +- [CloudEvent 属性](#CloudEvent-属性) +- [CloudEvent 属性扩展](#CloudEvent-属性扩展) +- [生产 CloudEvents](#生产CloudEvents) +- [合格的协议与编码](#合格的协议与编码) +- [专有的协议和编码](#专有的协议与编码) +- [现有技术](#现有技术) +- [角色](#角色) +- [价值主张](#价值主张) +- [现有的数据格式](#现有的数据格式) + +## 历史 + +[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 是由 CNCF的 +[技术监管委员会](https://github.com/cncf/toc) 成立，用于研究 +Serverless相关技术并为CNCF推荐相关领域的未来发展计划的。工作组其中一项建议就是研究创建一种通用事件格式， +用于提升不同云厂商间函数的可移植性和事件流处理的互操作性。就此，CloudEvents应运而生。 + +尽管CloudEvents起初是作为Serverless工作组的项目进行的，但随着CloudEvents规范完成它v0.1版本的里程碑， +技术监管委员会批准了CloudEvents作为一个新的独立的CNCF沙箱级项目。 + +## CloudEvents-概念 + +一个[事件](spec.md#事件)包含了[事件发生](spec.md#发生)的上下文和相关数据。 +事件的相关数据可以用来唯一标识一件事件的发生。 + +事件代表了已发生的事实，因此它并不包含任何目的地相关信息，但消息能够传达事件内容，从而将事件数据 +从源头传输到指定的目的地。 + +### 事件使用 + +事件通常在服务器端代码中使用来连接不同的系统，其中一个系统中的状态变化会导致代码在另一个系统中执行。 +比如，一个事件源，可能会在收到某个外部信号(如HTTP或RPC)或观察到状态变化(如IoT传感器数据变化或不活跃) +时，生产一个事件。 + +为了更好地解释一个系统如何使用CloudEvents，下图展示了一个从事件源生产的事件是如何触发一个行为的。 + +![alt text](source-event-action.png "A box representing the source with +arrow pointing to a box representing the action. The arrow is annotated with +'e' for event and 'protocol'.") + +事件源生产了一条封装了基于某种协议的事件数据的消息。 +当载有事件的消息到达目的地时，会触发一个使用了事件数据的行为函数。 + +一个事件源是那些允许暂存和测试实例的源类型的特定实例。 +某个特定源类型的开源软件可能由多个公司或提供商部署。 + +事件可以通过各种行业标准协议（如HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或 +平台/供应商专有协议（AWS Kinesis、Azure Event Grid）传输。 + +一个操作函数能够处理那些定义了行为或影响的事件，这些行为和效果由来自特定源的特定事件触发而来。 +虽然超出了规范的范围，但生成事件的目的通常是让其他系统能够轻松地对它们无法控制的源中的更改做出反应。 +源和操作通常由不同的开发人员构建。 +通常，源是托管服务，而操作是serverless函数（如 AWS Lambda 或 Google Cloud Functions）中 +的自定义代码。 + +## 设计目标 + +CloudEvents 通常用于分布式系统，以允许服务在开发过程中松耦合，独立部署，方便之后连接以创建新的应用程序。 + +CloudEvents 规范的目标是定义允许服务生产或消费事件的事件系统的互操作性， +其中生产者和消费者可以独立开发和部署。 生产者可以在没有消费者监听时就生成事件， +消费者也可以表达对尚未生成的事件或事件类的兴趣。值得注意的是，这项工作产生的规范侧重于事件格式的互操作性 +以及它在通过各种协议（例如 HTTP）发送时的显示方式。我们不关注事件生产者或事件消费者的处理模型。 + +CloudEvents的核心规范中定义了一组称之为属性的元数据， +它们描述了在系统之间传输的事件以及这些元数据片段应如何显示在该消息中。 +这些元数据是，将请求路由到适当组件并帮助该组件正确处理事件所需的最小信息集。 +因此，某些事件本身的数据可能会作为 CloudEvent 属性集的一部分而被复制， +但这样做仅是为了能够正确传递和处理消息。那些不用于该目的的数据应放置在事件（数据）本身中。 + +此外，本规范中假设协议层所需的用来将消息传递到目标系统的元数据应完全由协议处理， +因此不包含在 CloudEvents 属性中。 有关更多详细信息，请参阅[非目标](#非目标)部分。 + +除了这些属性的定义之外，规范还描述了关于如何序列化 +不同格式（例如 JSON）和协议（例如 HTTP、AMQP、Kafka）的事件。 + +一些协议本身支持将多个事件批处理到单个 API 的调用中。 +为了提升系统间的互操作性，是否以及如何实现批处理将由协议自己决定。 +相关详细信息可以在协议绑定或协议规范中找到。 +成批的CloudEvents并没有语义，也没有排序。 +[中间人](spec.md#中间人)可以添加或删除批处理以及将事件分配给不同的批处理。 + +### 非目标 + +以下内容不在本规范的范围之内： + +- 函数的构建和调用过程 +- 特定语言的运行时 APIs +- 选择单一身份认证或访问控制的系统 +- 包含协议级路由信息 +- 事件持久化过程 + +就连那些刚接触 CloudEvents 概念的人都会建议 +CloudEvents 规范不应包括协议级路由信息（例如，将事件发送到的目标的URL）。 +经过深思熟虑，工作组得出的结论是，CloudEvents规范中不需要路由信息： +因为任何现有的协议（例如 HTTP、MQTT、XMPP 或 Pub/Sub 总线）都已经定义了路由语义。 +例如，CloudEvents [HTTP 绑定](http-protocol-binding.md) 规定了头部和请求正文内容。 +CloudEvents 不需要在规范中包含目标 URL 即可与 HTTP 兼容；HTTP 规范已经在 +[请求行](https://tools.ietf.org/html/rfc2616#section-5.1) 中包含了所需的目标URL。 + +路由信息不仅是多余的，而且是有害的。 +CloudEvents 应该增加互操作性并解耦事件的生产者和消费者。 +禁止来自事件格式的路由信息允许将 CloudEvents 重新传送到新的行为，或通过包含多个通道的复杂中继传送。 +例如，如果 Webhook 地址不可用，则用于 Webhook 的 CloudEvent 应可传送到死信队列。 +死信队列应该能够将事件传送给原始事件发射者从未想象过的新的行为上。 + +在系统内和跨系统生产和消费的 CloudEvent能够触发产生价值的行为。 +因此，对于调试或复制的目的而言，存档和或重放事件可能很有价值。 +但是，持久化事件会删除传输期间可用的上下文信息，例如生产者的身份和权利、保真验证机制或机密性保护。 +此外，持久化会增加满足用户需求的复杂性和挑战。 +例如，出于加密或签名目的重复使用私钥会增加攻击者可用的信息，从而降低安全性。 +因此我们推测，可以定义有助于满足持久性要求的属性，但这些属性可能随着行业最佳实践和进步而不断发展。 + +## 架构 +CloudEvents 规范集定义了四种有助于形成分层架构模型的不同类型的协议元素。 +基本规范定义了一个抽象信息模型，该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 + +1. [基本规范](spec.md) 定义了一个抽象信息模型， + 该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 +2. [扩展属性](./spec.md#扩展上下文属性) + 添加了特定于用例且可能重叠的扩展属性集和相关规则，如支持不同的追踪标准的规则。 +3. 事件格式编码,如 [JSON](json-format.md), 定义了基本规范的信息模型与所选扩展的编码方式， + 以将其映射到应用程序协议的头部和负载元素。 +4. 协议绑定, 如. [HTTP协议绑定](http-protocol-binding.md), + 在HTTP to HTTP的情况下， + 定义了 CloudEvent 如何绑定到应用程序协议的传输层 。 + 协议绑定不限制传输层的使用方式，这意味着 HTTP绑定可用于任何 HTTP方法以及请求和响应消息。 + +为了确保更广泛的互操作性，CloudEvents规范集为使用专有应用协议的事件传输提供了特定约束。 +[HTTP Webhook](http-webhook.md)规范并非特定于 CloudEvents， +而是可用于将任何类型的单向事件和通知发布到符合标准的 HTTP 端点。 +但是，由于其他地方缺乏此类规范，因此 CloudEvents 需要对其进行定义。 + +### 协议错误处理 + +CloudEvents 规范在很大程度上并未规定与 CloudEvents 的创建或处理相关联的处理模型。 +因此，如果在处理 CloudEvent 过程中出现错误， +请使用正常的协议级错误处理机制进行处理。 + +## 属性版本控制 + +对于某些 CloudEvents 属性，由其值引用的实体或数据模型可能会随时间变化。 +例如，`dataschema`可能引用模式文档的一个特定版本。 +通常，这些属性值会通过将一些特定于版本的字符串作为其值的一部分来区分每个变体。 +例如，可能会加入版本号 (v1, v2) 或日期 (2018-01-01)来区分。 + +CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强制使用版本字符串。 +是否使用完全取决于每个事件生产者。 +但是，当使用特定版本的字符串时，每当其值发生变化时都应注意， +因为事件消费者可能依赖于现有值，因此更改可能被解释为“破坏性更改”。 +应该在生产者和消费者之间建立某种形式的通信，以确保事件消费者知道能使用哪些可能的值。 +通常，这也适用于所有 CloudEvents 属性。 + +## CloudEvent-属性 + +本节介绍了与CloudEvent 属性相关的其他背景和设计要点。 + +### id + +`id` 属性是一个在同一事件源下所有事件中用来标识事件唯一的值 +（其中每个事件源由其 CloudEvents `source`属性唯一标识）。 +虽然`id`使用的确切值是生产者定义的， +但必须要确保来自单个事件源的 CloudEvents 消费者不会有两个事件共享相同的 id 值。 +唯一的例外是如果支持事件的重播，在这些情况下，可以使用 id 来检测这一点。 + +由于一次事件的发生可能导致生成多个cloud event， +在所有这些事件都来自同一事件源的情况下， +生成的每个 CloudEvent 将具有唯一的 `id`。 +以创建数据库条目为例，这一事件的发生可能会生成一个类型为 create 的 CloudEvent +和一个类型为 write 的 CloudEvent。 +这两个 CloudEvents 各自都有一个唯一的 ID。 +如果需要在这两个 CloudEvent 之间建立某种关联以表明它们都与同一事件相关， +那么可以使用 CloudEvent 中的一些附加数据来实现该目的。 + +从这方面来看，虽然事件生产者对`id`的使用可能是某个随机字符串， +或者在其它上下文中具有某种语义的字符串， +但对于此 CloudEvent 属性而言，这些含义并不成立， +因此本规范不建议将 `id` 用于除了唯一性检查之外的其它目的。 + +## CloudEvent-属性扩展 + +为了实现规范的设计目标， +规范作者将尝试限制他们在 CloudEvents 中定义的元数据属性的数量。 +为此，该项目定义的属性将分为以下三类： + +- 必要属性 +- 可选属性 +- 扩展属性 + +正如类别名称所暗示的那样， +“必要”属性是工作组认为在任何情况下，对所有事件都至关重要的属性， +而“可选”属性将在大多数情况下使用。 这些情况下的两个属性都在本规范中定义了出来。 + +工作组考虑到某些属性不够常见而不能归入上述两个类别， +但此类属性的良好定义仍会使系统间的互操作性级别受益， +因此将这些属性放入了“扩展”类别并记录在[扩展文档](documented-extensions.md)中， +本规范定义了这些扩展属性在 CloudEvent 中的显示方式。 + +在确定提议的属性属于哪个类别时， +工作组使用现有的用例和用户故事来解释它们的基本原理和需求。 +相关信息将添加到本文档的[现有技术](#现有技术)部分。 + +CloudEvent 规范的扩展属性是需要包含的附加元数据，它们能确保正确的路由和正确处理CloudEvent。 +用于其它目的的附加元数据， +即那些与事件本身相但在 CloudEvent 的传输或处理中不需要的元数据， +应改为放置在事件 (`data`)的扩展点内。 + +扩展属性应保持最少，以确保 CloudEvent 可以正确序列化和传输。 +事件生产者应该考虑在向 CloudEvent 添加扩展时可能遇到的技术限制。 +例如，[HTTP Binary Mode](http-protocol-binding.md#31-binary-content-mode) +使用 HTTP 头来传输元数据； +大多数 HTTP 服务器会拒绝包含过多 HTTP 头部数据的请求，要求限制其低至 8kb。 +因此，扩展属性的大小和数量应保持最小。 + +如果扩展变得流行，那么规范作者可能会考虑将其作为核心属性移入规范。 +这意味着在正式将新属性添加到规范之前，扩展机制/过程可用作审查新属性的一种方式。 + +### JSON 扩展 + +如 [CloudEvents JSON 事件格式](json-format.md)中 +[属性](json-format.md#2-attributes)部分所述， +CloudEvent 扩展属性与已定义属性(必要属性、可选属性)在序列化时处于同一等级 - +也就是说，它们都是 JSON 对象的顶层属性。 +CloudEvent的作者花了很长时间考虑所有选项，并认为这是最好的选择。 +理由如下： + +由于CloudEvents规范遵循 [semver](https://semver.org/) ， +这意味着只要新属性是可选属性，它们可以在核心规范的未来版本定义，而无需更改当前主要版本。 +在这样的情况下，请考虑现有消费者将如何使用新的（未知的）顶级属性。 +虽然消费者可以随意忽略它，因为它是可选的， +但在大多数情况下，这些属性仍然希望向接收这些事件的应用程序公开。 +这可能导致这些应用程序在基础设施不支持的情况下，支持这些属性。 +这意味着未知的顶级属性（无论是谁定义的——规范的未来版本或事件生产者）可能不会被忽略。 +因此，虽然其它一些规范定义了放置扩展的特定属性（例如顶级`extensions`属性）， +但作者认为在传入事件中具有两个不同位置的未知属性可能会导致互操作性问题和开发人员的混淆。 + +扩展属性通常用于测试那些被规范正式采用之前的潜在属性。 +如果有一个`extensions`类型的属性，这个新属性已经被序列化， +那么如果该属性被核心规范采用，它将从`extensions`属性提升（从序列化的角度）为顶级属性。 +如果我们假设这个新属性是可选的，那么当它被核心规范采用时， +它只是一个小版本增量，所有现有的消费者仍然会继续工作。 +但是，消费者将不知道此属性将出现在何处 - 在扩展属性中还是作为顶级属性。 +这意味着他们可能需要同时查看两个地方。 +如果属性出现在两个地方但具有不同的值怎么办？ +生产者是否需要将它放在两个地方，因为他们可能同时有新、老消费者？ +虽然可以为如何解决出现的每个潜在问题而制定明确的规则， +但作者认为一个避免这些问题的更好的办法是在序列化中只有一个位置来放置未知的甚至是新的属性。 +作者还注意到 HTTP 规范现在遵循类似的模式，不再建议扩展 HTTP 头部以 X- 为前缀。 + +## 生产CloudEvents + +CloudEvents 规范有意避免将CloudEvents 的创建方式设计的过于死板。 +例如，它不假定原始事件源必须是该事件生产对应 CloudEvent 的同一实体。 +这允许多种实现方式。 +但是，对于规范的实现者来说，理解规范作者心中的期望还是有帮助的，因为这将有助于确保互操作性和一致性。 + +如上所述，生成初始事件的实体是否与创建相应 CloudEvent 的实体相同是由实现决定的。 +但是，当构建/填充 CloudEvents 属性的实体代表事件源进行操作时，这些属性的值是用来描述事件或事件源， +而不是计算 CloudEvent 属性值的实体的。 +换句话说，当事件源和 CloudEvents 生产者之间的分离对事件使用者没有实质性意义时， +规范定义的属性通常不会包含任何值来指示这种职责分离。 + +这并不是说 CloudEvents 生产者不能向 CloudEvent 添加一些额外的属性， +但这些属性超出了规范的互操作性定义属性的范围。 +这类似于 HTTP 代理通常如何最大限度地减少对传入消息的明确定义的 HTTP 头部的更改， +但它可能会添加一些额外的头部，其中包括一些特定代理的元数据。 + +还值得注意的是，原始事件源和 CloudEvents 生产者之间的这种分离可大可小。 +意思是，即使 CloudEvent 生产者不是原始事件源生态系统的一部分， +如果它代表事件源行事，并且它在事件流中的存在对事件消费者没有意义，那么上述指导仍然适用。 + +当实体同时充当 CloudEvents 的接收者和发送者以转发或转换传入事件时， +出站 CloudEvent 与入站 CloudEvent 匹配的程度将根据该实体的处理语义而有所不同。 +在它充当代理的情况下，它只是将 CloudEvents 转发给另一个事件消费者， +那么出站 CloudEvent 通常看起来与入站 CloudEvent 就规范定义的属性相同 +- 请参阅上一段有关添加其他属性的内容。 + +但是，如果此实体正在执行 CloudEvent 的某种类型的语义处理， +通常会导致`data`属性值发生更改， +则可能需要将其视为与原始事件源不同的“事件源”。 +因此，与事件生产者相关的 CloudEvents 属性（例如`source` and `id`） +将从传入的 CloudEvent 中更改。 + +## 合格的协议与编码 + +正如规范中所表达的，CloudEvents 工作的明确目标是 +“以通用方式描述事件数据”且 +“定义允许服务产生或消费事件的事件系统的互操作性，其中生产者和消费者可以被独立开发和部署”。 + +这种互操作性的基础是开放的数据格式和协议， +CloudEvents 旨在提供这种开放的数据格式，并将其数据格式映射到常用协议和常用编码上。 + +虽然每个软件或服务产品和项目都可以自己选择自己喜欢的通信形式， +但毫无疑问，这种产品或项目私有的专有协议无法进一步实现跨生产者和消费者的广泛互操作性的目标。 + +特别是在消息传递和事件处理领域，该行业在过去十年中开发出了强大且受到广泛支持的协议 +例如 HTTP 1.1 和 HTTP/2 以及 WebSockets 或 Web 上的事件，或者 MQTT 和 AMQP +用于面向连接的消息传递和遥测传输的协议。 + +一些广泛使用的协议已经成为事实上的标准，这些协议来自三个或更多公司的顶级财团打造的强大生态系统， +还有一些来自单个公司发布的强大项目生态系统，在任何一种情况下都与前面提到的标准栈的演变相一致。 + +CloudEvents的努力不应成为认可或推广项目或产品专有协议的工具， +因为这与CloudEvents 的原始目标背道而驰。 + +要使协议或编码符合核心 CloudEvents 事件格式或协议绑定的条件，它必须属于以下任一类别： + +- 该协议具有广泛认可的多供应商协议标准化机构（例如 W3C、IETF、OASIS、ISO）的正式标准地位 +- 该协议在其生态系统类别中具有“事实上的标准”地位， + 这意味着它被广泛使用，甚至被认为是给定应用程序的标准。 + 实际上，我们希望在供应商中立的开源组织（例如 Apache、Eclipse、CNCF、.NET 基金会）的保护伞下 + 看到至少一个开源实现， + 并且至少有十几个独立供应商在他们的产品中使用它的产品或服务。 + +除了正式状态之外，协议或编码是否符合核心 CloudEvents 事件格式或协议绑定的一个关键标准是， +该组织是否认为协议或编码出现后，该规范对与产品或项目无关的任何一方具有持续的实际利益。 +对此的基本要求是协议或编码的定义方式允许独立于产品或项目代码的替代实现。 + +欢迎将 CloudEvents 的所有其他协议和编码格式 +包含在指向相应项目自己的公共仓库，或站点中的 CloudEvents binding信息的列表中。 + +## 专有的协议与编码 + +为了鼓励更多人采用 CloudEvents，本仓库将自动收集专有协议和编码。 +本仓库的维护人员不负责创建、维护或通知专有规范的维护人员有关专有规范和CloudEvents规范间的偏差。 + +专有规范将托管在他们自己的仓库或文档站点中，并记录在[专有规范](proprietary-specs.md) +文件中。 专有规范应遵循与核心协议和编码相关的其他规范相同的格式。 + +专有规范将比核心规范受到更少的审查，并且随着 CloudEvents 规范的发展， +相应协议和编码的维护者有责任使规范与 CloudEvents 规范保持同步。 +如果专有规范过时太多，CloudEvents 可能会将指向该规范的链接标记为已弃用或将其删除。 + +如果为同一个协议创建了多个不兼容的规范，存储库维护者将不知道哪个规范是正确的，并列出所有规范的链接。 + +## 现有技术 + +本节介绍了工作组在 CloudEvent 规范开发过程中使用的一些输入材料。 + +### 角色 + +下面列举了可能涉及事件的产生、管理或消费的各种参与者和场景。 + +在这些中，事件生产者和事件消费者的角色是不同的。 +单个应用程序上下文背景始终可以同时承担多个角色，包括既是事件的生产者又是事件的消费者。 + +1. 应用程序生成供他人使用的事件， + 如为消费者提供有关终端用户活动、状态变化或环境观察的见解， + 或允许通过事件驱动的扩展来补充应用程序的功能。 + + 生产的事件通常与上下文或生产者选择的分类相关。 + 例如，房间中的温度传感器可能被安装位置、房间、楼层和建筑物等上下文限定。 + 运动结果可以按联赛和球队分类。 + + 生产者应用程序可以在任何地方运行，例如在服务器或设备上。 + + 生产的事件可能由生产者或中间人直接提供和发出； + 作为后者的示例，请考虑设备通过负载大小受限的网络（如 LoRaWAN 或 ModBus）传输的事件数据， + 并且符合此规范的事件将由网络网关代表生产者提供。 + + 例如，气象站每 5 分钟通过 LoRaWAN 传输一次 12 字节的专有事件payload用于指示天气状况。 + 然后使用 LoRaWAN 网关以 CloudEvents 格式将事件发布到 Internet 目标。 + LoRaWAN 网关是事件生产者，代表气象站发布事件，并将设置一定的元数据以反映事件的来源(气象站)。 + +2. 应用程序可能以以下目的： + 如显示、存档、分析、工作流处理、监控状态或提供业务解决方案及其基本构建模块的透明化 + 来消费事件。 + + 消费者应用程序可以在任何地方运行，例如在服务器或设备上。 + + 消费应用程序通常对以下内容感兴趣： + + - 区分事件，使得完全相同的事件不会被处理两次。 + - 识别和选择源上下文或生产者指定的分类。 + - 确定事件相对于原始上下文或相对于时钟的时间顺序。 + - 了解事件中携带的上下文相关的详细信息。 + - 关联来自多个事件生产者的事件实例并将它们发送到相同的消费者上下文。 + + 在某些情况下，消费应用程序可能对以下内容感兴趣： + + - 从原始上下文中获取有关事件主题的更多详细信息，例如获取有关需要特权访问授权的已更改对象的详细信息。 + 例如，出于隐私原因，HR 解决方案可能仅在事件中发布非常有限的信息， + 任何需要更多数据的事件消费者都必须在其自己的授权上下文背景下从 HR 系统获取与事件相关的详细信息 + - 在原始上下文中与事件的主题进行交互，例如在被告知该数据块刚刚创建后读取存储该数据块。 + + 消费者的兴趣激发了信息生产者应该包括事件的需求。 + +3. 中间件将事件从生产者路由到消费者，或转发到其他中间件。 + 产生事件的应用程序可能会将根据消费者需求产生的某些任务委托给中间件： + + - 管理同时对大量类别和上下文背景中的某个事件感兴趣的消费者。 + - 代表消费者在类或事件的原始上下文上处理过滤条件。 + - 转码，比如从 JSON 解码后在 MsgPack 中编码。 + - 更改事件结构的转换，例如从专有格式映射到 CloudEvents，同时保留事件的身份和语义完整性。 + - 即时“推送式”传输给感兴趣的消费者。 + - 存储最终传输的事件，用于由消费者发起的“拉”请求，或延迟后由中间件发起“推”请求。 + - 观察事件内容或事件流以进行监控或诊断。 + + 为了满足这些需求，中间件将对以下方面感兴趣： + + - 一种元数据鉴别器，可用于事件的分类或上下文化，以便消费者可以表达对一个或多个类或上下文的兴趣。 + 例如，消费者可能对文件存储帐户内的特定目录相关的所有事件感兴趣。 + - 一种元数据鉴别器，允许区分该类或上下文的特定事件的主题。例如，消费者可能希望过滤掉与以“.jpg”结尾的 + 新文件相关的所有事件（文件名是“新文件”事件的主题），以此表示它对感兴趣的文件存储账户下某个目录的 + 上下文环境。 + - 一个事件及其数据编码的指示器。 + - 一个事件及其数据的结构布局（模式）的指示器。 + + 事件是否可通过中间件消费取决于生产者的选择。 + + 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec.md#生产者)的角色， + 当它根据事件采取行动时可以扮演[消费者](spec.md#消费者)的角色， + 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec.md#中间人)的角色。 + +4. 框架和其他抽象使与事件平台基础设施间的交互更简单， + 并且通常为多个事件平台基础设施提供公共 API 区域。 + + 框架通常用于将事件转换为对象图，并将事件分派给某些特定的处理逻辑或用户规则， + 这些用户逻辑或用户规则允许消费应用程序对原始上下文和特定主题中的特定类型的事件做出反应。 + + 框架最感兴趣的是跨抽象平台的语义元数据通用性，以便可以统一处理类似的活动。 + + 对于体育应用程序，使用该框架的开发人员可能对联盟中一支球队今天的比赛（主题） + 的所有事件感兴趣，但希望以不同于“换人”事件的方式处理“得分”事件。 + 为此，框架将需要一个合适的元数据鉴别器，使其不必了解事件细节。 + +### 价值主张 + +本节介绍了一些能够展示 CloudEvents 价值主张的用例。 + +#### 跨服务和平台规范化事件 + +主要事件发布者（例如 AWS、Microsoft、Google 等）都在各自的平台上以不同的格式发布事件。 +甚至在少数情况下，同一提供商的服务以不同格式（例如 AWS）发布事件。 +这迫使事件消费者实现自定义逻辑以跨平台读取或处理事件数据，有时甚至需要跨单个平台的多个服务处理。 + +CloudEvents 可以为那些跨平台和服务处理事件的使用者提供单一体验。 + +#### 促进跨服务和平台的集成 + +跨环境传输的事件数据越来越普遍。 +然而，如果没有描述事件的通用方式，跨环境的事件传递就会受到阻碍。 +CloudEvents之前没有单一的方法可以确定事件的来源和可能的去向。 +这对研究成功传输事件事件工具和消费者知道如何处理事件数据形成了巨大阻碍。 + +CloudEvents 提供有用的元数据，中间件和消费者可以依赖这些元数据来促进事件路由、日志记录、传输和接收。 + +#### 提高功能即服务的可移植性 + +功能即服务（也称为serverless计算）是 IT 中增长最快的趋势之一，它主要是由事件驱动的。 +然而，FaaS 的一个主要问题是供应商锁定。 +这种锁定部分是由函数 API 和供应商之间签名的差异引起的， +锁定同样也是由函数内接收的事件数据格式的差异引起的。 + +CloudEvents提供描述事件数据的通用方式提高了功能即服务的可移植性。 + +#### 改进事件驱动/serverless架构的开发和测试 + +缺乏通用事件格式使事件驱动和serverless架构的开发和测试变得复杂。 +没有简单的方法可以准确地为开发和测试目的模拟事件，并帮助在开发环境中模拟事件驱动的工作流。 + +CloudEvents 可以提供更好的开发工具来构建、测试和处理事件驱动和无服务器架构的端到端生命周期。 + +#### 事件数据发展 + +大多数平台和服务对其事件的数据模型进行不同的版本控制（如果他们这样做的话）。 +随着这些数据模型的发展，这会为发布和使用事件的数据模型带来不一致的体验。 + +CloudEvents 可以提供一种通用的方式来版本化和演化事件数据的发展。 +这将帮助事件发布者根据最佳实践安全地对其数据模型进行版本控制， +并且这有助于事件消费者随着事件数据的发展安全地使用它。 + +#### 规范化 Webhook + +Webhooks 是一种不使用通用格式的来发布事件的模式。 +Webhook 的使用者没有一致的方式来开发、测试、识别、验证和整体处理通过 Webhook 传输的事件数据。 + +CloudEvents 可以提供 Webhook 发布和消费事件的一致性。 + +#### 安全策略 + +出于安全和策略考虑，可能需要过滤、转换或阻止系统之间的事件传输。 +比如可能需要防止事件的进入或退出，如包含敏感信息的事件数据或想要禁止发送方和接收方之间的信息流。 + +通用事件格式将允许更容易地推理正在传输的数据，并提供更好的数据自查。 + +#### 事件追踪 + +从源发送的事件可能会出现在一系列附加事件序列之中， +这些附加事件序列从各种中间件设备（例如事件代理和网关）发出。 +CloudEvents 在事件中包含元数据以将这些事件关联为事件序列的一部分，以便进行事件跟踪和故障排除。 + +#### IoT + +物联网设备会发送和接收与其功能相关的事件。 +例如，连接的恒温器将发送有关当前温度的遥测数据， +并可以接收改变温度的事件。 +这些设备通常具有受限的操作环境（cpu、内存），需要明确定义的事件消息格式。 +在很多情况下，这些消息是二进制编码的，而不是文本的。 +无论是直接来自设备还是通过网关转换，CloudEvents 都可以更好地描述消息的来源和消息中包含的数据格式。 + +#### 事件关联 + +一个serverless应用或工作流可能与来自不同事件源或事件生产者的多个事件相关联。 +例如，盗窃检测应用程序/工作流可能涉及运动事件和门/窗打开事件。 +一个serverless平台可能接收每种类型事件的许多实例，例如 它可以接收来自不同房屋的运动事件和开窗事件。 + +serverless平台需要将一种类型的事件实例与其他类型的事件实例正确关联， +并将接收到的事件实例映射到正确的应用/工作流实例。 +CloudEvents 将为任何事件使用者（例如serverless平台）提供一种标准方式， +以在事件数据中定位事件关联信息/令牌并将接收到的事件实例映射到正确的应用/工作流实例。 + +### 现有的数据格式 + +与上一节一样，对当前现状的调查（和理解）对CloudEvents 小组来说非常重要。 +为此，下面列出了在实践中被广泛使用的当前事件格式的样本。 + +#### Microsoft - Event Grid + +``` +{ + "topic":"/subscriptions/{subscription-id}", + "subject":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/eventSubscriptions/LogicAppdd584bdf-8347-49c9-b9a9-d1f980783501", + "eventType":"Microsoft.Resources.ResourceWriteSuccess", + "eventTime":"2017-08-16T03:54:38.2696833Z", + "id":"25b3b0d0-d79b-44d5-9963-440d4e6a9bba", + "data": { + "authorization":"{azure_resource_manager_authorizations}", + "claims":"{azure_resource_manager_claims}", + "correlationId":"54ef1e39-6a82-44b3-abc1-bdeb6ce4d3c6", + "httpRequest":"", + "resourceProvider":"Microsoft.EventGrid", + "resourceUri":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/eventSubscriptions/LogicAppdd584bdf-8347-49c9-b9a9-d1f980783501", + "operationName":"Microsoft.EventGrid/eventSubscriptions/write", + "status":"Succeeded", + "subscriptionId":"{subscription-id}", + "tenantId":"72f988bf-86f1-41af-91ab-2d7cd011db47" + } +} +``` + +[Documentation](https://docs.microsoft.com/en-us/azure/event-grid/event-schema) + +#### Google - Cloud Functions (potential future) + +``` +{ + "data": { + "@type": "types.googleapis.com/google.pubsub.v1.PubsubMessage", + "attributes": { + "foo": "bar", + }, + "messageId": "12345", + "publishTime": "2017-06-05T12:00:00.000Z", + "data": "somebase64encodedmessage" + }, + "context": { + "eventId": "12345", + "timestamp": "2017-06-05T12:00:00.000Z", + "eventTypeId": "google.pubsub.topic.publish", + "resource": { + "name": "projects/myProject/topics/myTopic", + "service": "pubsub.googleapis.com" + } + } +} +``` + +#### AWS - CloudWatch Events + +AWS 上的很大一部分事件处理系统都在使用这种格式。 + +``` +{ + "version": "0", + "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718", + "detail-type": "EC2 Instance State-change Notification", + "source": "aws.ec2", + "account": "111122223333", + "time": "2017-12-22T18:43:48Z", + "region": "us-west-1", + "resources": [ + "arn:aws:ec2:us-west-1:123456789012:instance/i-1234567890abcdef0" + ], + "detail": { + "instance-id": "i-1234567890abcdef0", + "state": "terminated" + } +} +``` + +#### IBM - OpenWhisk - Web Action Event + +``` +{ + "__ow_method": "post", + "__ow_headers": { + "accept": "*/*", + "connection": "close", + "content-length": "4", + "content-type": "text/plain", + "host": "172.17.0.1", + "user-agent": "curl/7.43.0" + }, + "__ow_path": "", + "__ow_body": "Jane" +} +``` + +#### OpenStack - Audit Middleware - Event + +``` +{ + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + "id": "d8304637-3f63-5092-9ab3-18c9781871a2", + "eventTime": "2018-01-30T10:46:16.740253+00:00", + "action": "delete", + "eventType": "activity", + "outcome": "success", + "reason": { + "reasonType": "HTTP", + "reasonCode": "204" + }, + "initiator": { + "typeURI": "service/security/account/user", + "name": "user1", + "domain": "domain1", + "id": "52d28347f0b4cf9cc1717c00adf41c74cc764fe440b47aacb8404670a7cd5d22", + "host": { + "address": "127.0.0.1", + "agent": "python-novaclient" + }, + "project_id": "ae63ddf2076d4342a56eb049e37a7621" + }, + "target": { + "typeURI": "compute/server", + "id": "b1b475fc-ef0a-4899-87f3-674ac0d56855" + }, + "observer": { + "typeURI": "service/compute", + "name": "nova", + "id": "1b5dbef1-c2e8-5614-888d-bb56bcf65749" + }, + "requestPath": "/v2/ae63ddf2076d4342a56eb049e37a7621/servers/b1b475fc-ef0a-4899-87f3-674ac0d56855" +} +``` + +[Documentation](https://github.com/openstack/pycadf/blob/master/doc/source/event_concept.rst) + +#### Adobe - I/O Events + +``` +{ + "event_id": "639fd17a-d0bb-40ca-83a4-e78612bce5dc", + "event": { + "@id": "82235bac-2b81-4e70-90b5-2bd1f04b5c7b", + "@type": "xdmCreated", + "xdmEventEnvelope:objectType": "xdmAsset", + "activitystreams:to": { + "xdmImsUser:id": "D13A1E7053E46A220A4C86E1@AdobeID", + "@type": "xdmImsUser" + }, + "activitystreams:generator": { + "xdmContentRepository:root": "https://cc-api-storage.adobe.io/", + "@type": "xdmContentRepository" + }, + "activitystreams:actor": { + "xdmImsUser:id": "D13A1E7053E46A220A4C86E1@AdobeID", + "@type": "xdmImsUser" + }, + "activitystreams:object": { + "@type": "xdmAsset", + "xdmAsset:asset_id": "urn:aaid:sc:us:4123ba4c-93a8-4c5d-b979-ffbbe4318185", + "xdmAsset:asset_name": "example.jpg", + "xdmAsset:etag": "6fc55d0389d856ae7deccebba54f110e", + "xdmAsset:path": "/MyFolder/example.jpg", + "xdmAsset:format": "image/jpeg" + }, + "activitystreams:published": "2016-07-16T19:20:30+01:00" + } +} +``` + +[Documentation](https://www.adobe.io/apis/cloudplatform/events/documentation.html) From f326630bd2239cfd4bd393ffcecc013030d861be Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:27:32 +0800 Subject: [PATCH 19/60] Update primer.md --- primer.md | 1219 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 706 insertions(+), 513 deletions(-) diff --git a/primer.md b/primer.md index a5382f71f..367262195 100644 --- a/primer.md +++ b/primer.md @@ -1,539 +1,731 @@ -# CloudEvents 入门文档 - 1.0 版本 - -Declaration： This manual aims to provide a fast and brief introduction of CloudEvents -in Chinese for people who are new to CloudEvents. -Most of the content is translated from the original English version. -It is strongly recommended to read the English version if you find anything lost in translation. - -## 摘要 - -这份非技术规范文档用来为你提供关于CloudEvents规范的总体概览。它补充了CloudEvents规范的相关背景 -以及在制定 本规范时的历史和设计理念。这样，CloudEvents的核心规范就只需要关注Events规范的技术细节， -而不用过多地关心背景相关内容。 - -## 目录 - -- [历史](#历史) -- [CloudEvents 概念](#CloudEvents-概念) -- [设计目标](#设计目标) -- [架构](#架构) -- [属性版本控制](#属性版本控制) -- [CloudEvent 属性](#CloudEvent-属性) -- [CloudEvent 属性扩展](#CloudEvent-属性扩展) -- [生产 CloudEvents](#生产CloudEvents) -- [合格的协议与编码](#合格的协议与编码) -- [专有的协议和编码](#专有的协议与编码) -- [现有技术](#现有技术) -- [角色](#角色) -- [价值主张](#价值主张) -- [现有的数据格式](#现有的数据格式) - -## 历史 - -[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 是由 CNCF的 -[技术监管委员会](https://github.com/cncf/toc) 成立，用于研究 -Serverless相关技术并为CNCF推荐相关领域的未来发展计划的。工作组其中一项建议就是研究创建一种通用事件格式， -用于提升不同云厂商间函数的可移植性和事件流处理的互操作性。就此，CloudEvents应运而生。 - -尽管CloudEvents起初是作为Serverless工作组的项目进行的，但随着CloudEvents规范完成它v0.1版本的里程碑， -技术监管委员会批准了CloudEvents作为一个新的独立的CNCF沙箱级项目。 - -## CloudEvents-概念 - -一个[事件](spec.md#事件)包含了[事件发生](spec.md#发生)的上下文和相关数据。 -事件的相关数据可以用来唯一标识一件事件的发生。 - -事件代表了已发生的事实，因此它并不包含任何目的地相关信息，但消息能够传达事件内容，从而将事件数据 -从源头传输到指定的目的地。 - -### 事件使用 - -事件通常在服务器端代码中使用来连接不同的系统，其中一个系统中的状态变化会导致代码在另一个系统中执行。 -比如，一个事件源，可能会在收到某个外部信号(如HTTP或RPC)或观察到状态变化(如IoT传感器数据变化或不活跃) -时，生产一个事件。 - -为了更好地解释一个系统如何使用CloudEvents，下图展示了一个从事件源生产的事件是如何触发一个行为的。 +# CloudEvents Primer - Version 1.0 + +## Abstract + +This non-normative document provides an overview of the CloudEvents +specification. It is meant to complement the CloudEvent specification to provide +additional background and insight into the history and design decisions made +during the development of the specification. This allows the specification +itself to focus on the normative technical details. + +## Table of Contents + +- [History](#history) +- [CloudEvents Concepts](#cloudevents-concepts) +- [Design Goals](#design-goals) +- [Architecture](#architecture) +- [Versioning of Attributes](#versioning-of-attributes) +- [CloudEvent Attributes](#cloudevent-attributes) +- [CloudEvent Attribute Extensions](#cloudevent-attribute-extensions) +- [Creating CloudEvents](#creating-cloudevents) +- [Qualifying Protocols and Encodings](#qualifying-protocols-and-encodings) +- [Proprietary Protocols and Encodings](#proprietary-protocols-and-encodings) +- [Prior Art](#prior-art) +- [Roles](#roles) +- [Value Proposition](#value-proposition) +- [Existing Event Formats](#existing-event-formats) + +## History + +The [CNCF Serverless Working group](https://github.com/cncf/wg-serverless) was +originally created by the CNCF's +[Technical Oversight Committee](https://github.com/cncf/toc) to investigate +Serverless Technology and to recommend some possible next steps for some CNCF +related activities in this space. One of the recommendations was to investigate +the creation of a common event format to aid in the portability of functions +between Cloud providers and the interoperability of processing of event streams. +As a result, the CloudEvents specification was created. + +While initially the work on CloudEvents was done as part of the Serverless +Working group, once the specification reached its v0.1 milestone, the TOC +approved the CloudEvents work as a new stand-alone CNCF sandbox project. + +## CloudEvents Concepts + +An [event](spec.md#event) includes context and data about an +[occurrence](spec.md#occurrence). Each _occurrence_ is uniquely identified by +the data of the _event_. + +_Events_ represent facts and therefore do not include a destination, whereas +messages convey intent, transporting data from a source to a given destination. + +### Eventing + +Events are commonly used in server-side code to connect disparate systems where +the change of state in one system causes code to execute in another. For +example, a source may generate an event when it receives an external signal +(e.g. HTTP or RPC) or observes a changing value (e.g. an IoT sensor or period of +inactivity). + +To illustrate how a system uses CloudEvents, the simplified diagram below shows +how an event from a [source](spec.md#source) triggers an action. ![alt text](source-event-action.png "A box representing the source with arrow pointing to a box representing the action. The arrow is annotated with 'e' for event and 'protocol'.") -事件源生产了一条封装了基于某种协议的事件数据的消息。 -当载有事件的消息到达目的地时，会触发一个使用了事件数据的行为函数。 - -一个事件源是那些允许暂存和测试实例的源类型的特定实例。 -某个特定源类型的开源软件可能由多个公司或提供商部署。 - -事件可以通过各种行业标准协议（如HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或 -平台/供应商专有协议（AWS Kinesis、Azure Event Grid）传输。 - -一个操作函数能够处理那些定义了行为或影响的事件，这些行为和效果由来自特定源的特定事件触发而来。 -虽然超出了规范的范围，但生成事件的目的通常是让其他系统能够轻松地对它们无法控制的源中的更改做出反应。 -源和操作通常由不同的开发人员构建。 -通常，源是托管服务，而操作是serverless函数（如 AWS Lambda 或 Google Cloud Functions）中 -的自定义代码。 - -## 设计目标 - -CloudEvents 通常用于分布式系统，以允许服务在开发过程中松耦合，独立部署，方便之后连接以创建新的应用程序。 - -CloudEvents 规范的目标是定义允许服务生产或消费事件的事件系统的互操作性， -其中生产者和消费者可以独立开发和部署。 生产者可以在没有消费者监听时就生成事件， -消费者也可以表达对尚未生成的事件或事件类的兴趣。值得注意的是，这项工作产生的规范侧重于事件格式的互操作性 -以及它在通过各种协议（例如 HTTP）发送时的显示方式。我们不关注事件生产者或事件消费者的处理模型。 - -CloudEvents的核心规范中定义了一组称之为属性的元数据， -它们描述了在系统之间传输的事件以及这些元数据片段应如何显示在该消息中。 -这些元数据是，将请求路由到适当组件并帮助该组件正确处理事件所需的最小信息集。 -因此，某些事件本身的数据可能会作为 CloudEvent 属性集的一部分而被复制， -但这样做仅是为了能够正确传递和处理消息。那些不用于该目的的数据应放置在事件（数据）本身中。 - -此外，本规范中假设协议层所需的用来将消息传递到目标系统的元数据应完全由协议处理， -因此不包含在 CloudEvents 属性中。 有关更多详细信息，请参阅[非目标](#非目标)部分。 - -除了这些属性的定义之外，规范还描述了关于如何序列化 -不同格式（例如 JSON）和协议（例如 HTTP、AMQP、Kafka）的事件。 - -一些协议本身支持将多个事件批处理到单个 API 的调用中。 -为了提升系统间的互操作性，是否以及如何实现批处理将由协议自己决定。 -相关详细信息可以在协议绑定或协议规范中找到。 -成批的CloudEvents并没有语义，也没有排序。 -[中间人](spec.md#中间人)可以添加或删除批处理以及将事件分配给不同的批处理。 - -### 非目标 - -以下内容不在本规范的范围之内： - -- 函数的构建和调用过程 -- 特定语言的运行时 APIs -- 选择单一身份认证或访问控制的系统 -- 包含协议级路由信息 -- 事件持久化过程 - -就连那些刚接触 CloudEvents 概念的人都会建议 -CloudEvents 规范不应包括协议级路由信息（例如，将事件发送到的目标的URL）。 -经过深思熟虑，工作组得出的结论是，CloudEvents规范中不需要路由信息： -因为任何现有的协议（例如 HTTP、MQTT、XMPP 或 Pub/Sub 总线）都已经定义了路由语义。 -例如，CloudEvents [HTTP 绑定](http-protocol-binding.md) 规定了头部和请求正文内容。 -CloudEvents 不需要在规范中包含目标 URL 即可与 HTTP 兼容；HTTP 规范已经在 -[请求行](https://tools.ietf.org/html/rfc2616#section-5.1) 中包含了所需的目标URL。 - -路由信息不仅是多余的，而且是有害的。 -CloudEvents 应该增加互操作性并解耦事件的生产者和消费者。 -禁止来自事件格式的路由信息允许将 CloudEvents 重新传送到新的行为，或通过包含多个通道的复杂中继传送。 -例如，如果 Webhook 地址不可用，则用于 Webhook 的 CloudEvent 应可传送到死信队列。 -死信队列应该能够将事件传送给原始事件发射者从未想象过的新的行为上。 - -在系统内和跨系统生产和消费的 CloudEvent能够触发产生价值的行为。 -因此，对于调试或复制的目的而言，存档和或重放事件可能很有价值。 -但是，持久化事件会删除传输期间可用的上下文信息，例如生产者的身份和权利、保真验证机制或机密性保护。 -此外，持久化会增加满足用户需求的复杂性和挑战。 -例如，出于加密或签名目的重复使用私钥会增加攻击者可用的信息，从而降低安全性。 -因此我们推测，可以定义有助于满足持久性要求的属性，但这些属性可能随着行业最佳实践和进步而不断发展。 - -## 架构 -CloudEvents 规范集定义了四种有助于形成分层架构模型的不同类型的协议元素。 -基本规范定义了一个抽象信息模型，该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 - -1. [基本规范](spec.md) 定义了一个抽象信息模型， - 该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 -2. [扩展属性](./spec.md#扩展上下文属性) - 添加了特定于用例且可能重叠的扩展属性集和相关规则，如支持不同的追踪标准的规则。 -3. 事件格式编码,如 [JSON](json-format.md), 定义了基本规范的信息模型与所选扩展的编码方式， - 以将其映射到应用程序协议的头部和负载元素。 -4. 协议绑定, 如. [HTTP协议绑定](http-protocol-binding.md), - 在HTTP to HTTP的情况下， - 定义了 CloudEvent 如何绑定到应用程序协议的传输层 。 - 协议绑定不限制传输层的使用方式，这意味着 HTTP绑定可用于任何 HTTP方法以及请求和响应消息。 - -为了确保更广泛的互操作性，CloudEvents规范集为使用专有应用协议的事件传输提供了特定约束。 -[HTTP Webhook](http-webhook.md)规范并非特定于 CloudEvents， -而是可用于将任何类型的单向事件和通知发布到符合标准的 HTTP 端点。 -但是，由于其他地方缺乏此类规范，因此 CloudEvents 需要对其进行定义。 - -### 协议错误处理 - -CloudEvents 规范在很大程度上并未规定与 CloudEvents 的创建或处理相关联的处理模型。 -因此，如果在处理 CloudEvent 过程中出现错误， -请使用正常的协议级错误处理机制进行处理。 - -## 属性版本控制 - -对于某些 CloudEvents 属性，由其值引用的实体或数据模型可能会随时间变化。 -例如，`dataschema`可能引用模式文档的一个特定版本。 -通常，这些属性值会通过将一些特定于版本的字符串作为其值的一部分来区分每个变体。 -例如，可能会加入版本号 (v1, v2) 或日期 (2018-01-01)来区分。 - -CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强制使用版本字符串。 -是否使用完全取决于每个事件生产者。 -但是，当使用特定版本的字符串时，每当其值发生变化时都应注意， -因为事件消费者可能依赖于现有值，因此更改可能被解释为“破坏性更改”。 -应该在生产者和消费者之间建立某种形式的通信，以确保事件消费者知道能使用哪些可能的值。 -通常，这也适用于所有 CloudEvents 属性。 - -## CloudEvent-属性 - -本节介绍了与CloudEvent 属性相关的其他背景和设计要点。 +The source generates a message where the event is encapsulated in a protocol. +The event arrives to a destination, triggering an action which is provided with +the event data. + +A _source_ is a specific instance of a source-type which allows for staging and +test instances. Open source software of a specific _source-type_ may be deployed +by multiple companies or providers. + +Events can be delivered through various industry standard protocols (e.g. HTTP, +AMQP, MQTT, SMTP), open-source protocols (e.g. Kafka, NATS), or platform/vendor +specific protocols (AWS Kinesis, Azure Event Grid). + +An action processes an event defining a behavior or effect which was triggered +by a specific _occurrence_ from a specific _source_. While outside of the scope +of the specification, the purpose of generating an _event_ is typically to allow +other systems to easily react to changes in a source that they do not control. +The _source_ and action are typically built by different developers. Often the +_source_ is a managed service and the _action_ is custom code in a serverless +Function (such as AWS Lambda or Google Cloud Functions). + +## Design Goals + +CloudEvents are typically used in a distributed system to allow for services to +be loosely coupled during development, deployed independently, and later can be +connected to create new applications. + +The goal of the CloudEvents specification is to define interoperability of event +systems that allow services to produce or consume events, where the producer and +consumer can be developed and deployed independently. A producer can generate +events before a consumer is listening, and a consumer can express an interest in +an event or class of events that is not yet being produced. Note that the +specifications produced by this effort are focused on interoperability of the +event format and how it appears while being sent on various protocols, such as +HTTP. The specifications will not focus on the processing model of either the +event producer or event consumer. + +CloudEvents, at its core, defines a set of metadata, called attributes, about +the event being transferred between systems, and how those pieces of metadata +should appear in that message. This metadata is meant to be the minimal set of +information needed to route the request to the proper component and to +facilitate proper processing of the event by that component. So, while this +might mean that some of the application data of the event itself might be +duplicated as part of the CloudEvent's set of attributes, this is to be done +solely for the purpose of proper delivery, and processing, of the message. Data +that is not intended for that purpose should instead be placed within the event +(`data`) itself. + +Additionally, it is assumed that the metadata needed by the protocol layer to +deliver the message to the target system is handled entirely by the protocol +and therefore is not included within the CloudEvents attributes. See the +[Non-Goals](#non-goals) section for more details. + +Along with the definition of these attributes, there will also be specifications +of how to serialize the event in different formats (e.g. JSON) and protocols +(e.g. HTTP, AMQP, Kafka). + +Batching of multiple events into a single API call is natively supported by some +protocols. To aid interoperability, it is left up to the protocols if and how +batching is implemented. Details may be found in the protocol binding or in the +protocol specification. A batch of CloudEvents carries no semantic meaning and +is not ordered. An [Intermediary](spec.md#intermediary) can add or remove +batching as well as assign events to different batches. + +### Non-Goals + +The following are considered beyond the scope of the specification: + +- Function build and invocation process +- Language-specific runtime APIs +- Selecting a single identity/access control system +- Inclusion of protocol-level routing information +- Event persistence processes + +The CloudEvents spec will not include protocol-level routing information (e.g. +a destination URL to which the event is being sent). This is a common suggestion +by those new to the concepts of CloudEvents. After much deliberation, the +working group has come to the conclusion that routing is unnecessary in the +spec: any protocol (e.g. HTTP, MQTT, XMPP, or a Pub/Sub bus) already +defines semantics for routing. For example, the CloudEvents +[HTTP binding](http-protocol-binding.md) dictates headers and request body +contents. CloudEvents don't need to include a destination URL in the spec to be +HTTP compatible; the HTTP spec already includes one in the +[Request-Line](https://tools.ietf.org/html/rfc2616#section-5.1). + +Routing information is not just redundant, it detracts. CloudEvents should +increase interoperability and decouple the producer and consumer of events. +Prohibiting routing information from the events format allows CloudEvents to be +redelivered to new actions, or to be delivered over complex relays that include +multiple channels. For example, a CloudEvent that was intended for a webhook +should be deliverable to a dead-letter queue if the webhook address is +unavailable. That dead-letter queue should be able to feed events to new actions +that the original event emitter never imagined. + +The CloudEvents that are produced and consumed within and across systems trigger +behaviors that derive value. As such, archiving and/or replaying events can be +valuable for debugging or replication purposes. However, persisting an event +removes the contextual information available during transmission such as the +identity and rights of the producer, fidelity validation mechanisms, or +confidentiality protections. Additionally, persistence can add complexity and +challenge to meeting user's requirements. For example, the repeated use of a +private key for encryption or signing purposes increases the information +available to attackers and thereby reduces security. It is expected that +attributes may be defined that facilitate meeting persistence requirements but +it is expected that these will continuously evolve along with industry best +practices and advancements. + +## Architecture + +The CloudEvents specification set defines four different kinds of protocol +elements that form a layered architecture model. + +1. The [base specification](spec.md) defines an abstract information model made + up of attributes (key-value pairs) and associated rules for what constitutes + a CloudEvent. +2. The [extensions](./spec.md#extension-context-attributes) add use-case + specific and potentially overlapping sets of extension attributes and + associated rules, e.g. to support different tracing standards. +3. The event format encodings, e.g. [JSON](json-format.md), define how the + information model of the base specification together with the chosen + extensions is encoded for mapping it to header and payload elements of an + application protocol. +4. The protocol bindings, e.g. [HTTP](http-protocol-binding.md), defines how + the CloudEvent is bound to an application protocol's transport frame, in the + case of HTTP to the HTTP message. The protocol binding does not constrain + how the transport frame is used, meaning that the HTTP binding can be used + with any HTTP method and with request and response messages. + +If required to assure broader interoperability, the CloudEvents specification +set provides specific constraints for event delivery using a particular +application protocol. The [HTTP Webhook](http-webhook.md) specification is not +specific to CloudEvents and can be used to post any kind of one-way event and +notifications to a conformant HTTP endpoint. However, the lack of such a +specification elsewhere makes it necessary for CloudEvents to define it. + +### Protocol Error Handling + +The CloudEvents specification, for the most part, does not dictate a processing +model associated with the creation or processing of CloudEvents. As such, if +there are errors during the processing of a CloudEvent, the software +encountering the error is encouraged to use the normal protocol-level error +reporting to report them. + +## Versioning of Attributes + +For certain CloudEvents attributes, the entity or data model referenced by its +value might change over time. For example, `dataschema` might reference one +particular version of a schema document. Often these attribute values will then +distinguish each variant by including some version-specific string as part of +its value. For example, a version number (`v1`, `v2`), or a date (`2018-01-01`) +might be used. + +The CloudEvents specification does not mandate any particular pattern to be +used, or even the use of version strings at all. This decision is up to each +event producer. However, when a version-specific string is included, care should +be taken whenever its value changes as event consumers might be reliant on the +existing value and thus a change could be interpreted as a "breaking change". +Some form of communication between producers and consumers should be established +to ensure the event consumers know what possible values might be used. In +general, this is true for all CloudEvents attributes as well. + +## CloudEvent Attributes + +This section provides additional background and design points related to some of +the CloudEvent attributes. ### id -`id` 属性是一个在同一事件源下所有事件中用来标识事件唯一的值 -（其中每个事件源由其 CloudEvents `source`属性唯一标识）。 -虽然`id`使用的确切值是生产者定义的， -但必须要确保来自单个事件源的 CloudEvents 消费者不会有两个事件共享相同的 id 值。 -唯一的例外是如果支持事件的重播，在这些情况下，可以使用 id 来检测这一点。 - -由于一次事件的发生可能导致生成多个cloud event， -在所有这些事件都来自同一事件源的情况下， -生成的每个 CloudEvent 将具有唯一的 `id`。 -以创建数据库条目为例，这一事件的发生可能会生成一个类型为 create 的 CloudEvent -和一个类型为 write 的 CloudEvent。 -这两个 CloudEvents 各自都有一个唯一的 ID。 -如果需要在这两个 CloudEvent 之间建立某种关联以表明它们都与同一事件相关， -那么可以使用 CloudEvent 中的一些附加数据来实现该目的。 - -从这方面来看，虽然事件生产者对`id`的使用可能是某个随机字符串， -或者在其它上下文中具有某种语义的字符串， -但对于此 CloudEvent 属性而言，这些含义并不成立， -因此本规范不建议将 `id` 用于除了唯一性检查之外的其它目的。 - -## CloudEvent-属性扩展 - -为了实现规范的设计目标， -规范作者将尝试限制他们在 CloudEvents 中定义的元数据属性的数量。 -为此，该项目定义的属性将分为以下三类： - -- 必要属性 -- 可选属性 -- 扩展属性 - -正如类别名称所暗示的那样， -“必要”属性是工作组认为在任何情况下，对所有事件都至关重要的属性， -而“可选”属性将在大多数情况下使用。 这些情况下的两个属性都在本规范中定义了出来。 - -工作组考虑到某些属性不够常见而不能归入上述两个类别， -但此类属性的良好定义仍会使系统间的互操作性级别受益， -因此将这些属性放入了“扩展”类别并记录在[扩展文档](documented-extensions.md)中， -本规范定义了这些扩展属性在 CloudEvent 中的显示方式。 - -在确定提议的属性属于哪个类别时， -工作组使用现有的用例和用户故事来解释它们的基本原理和需求。 -相关信息将添加到本文档的[现有技术](#现有技术)部分。 - -CloudEvent 规范的扩展属性是需要包含的附加元数据，它们能确保正确的路由和正确处理CloudEvent。 -用于其它目的的附加元数据， -即那些与事件本身相但在 CloudEvent 的传输或处理中不需要的元数据， -应改为放置在事件 (`data`)的扩展点内。 - -扩展属性应保持最少，以确保 CloudEvent 可以正确序列化和传输。 -事件生产者应该考虑在向 CloudEvent 添加扩展时可能遇到的技术限制。 -例如，[HTTP Binary Mode](http-protocol-binding.md#31-binary-content-mode) -使用 HTTP 头来传输元数据； -大多数 HTTP 服务器会拒绝包含过多 HTTP 头部数据的请求，要求限制其低至 8kb。 -因此，扩展属性的大小和数量应保持最小。 - -如果扩展变得流行，那么规范作者可能会考虑将其作为核心属性移入规范。 -这意味着在正式将新属性添加到规范之前，扩展机制/过程可用作审查新属性的一种方式。 - -### JSON 扩展 - -如 [CloudEvents JSON 事件格式](json-format.md)中 -[属性](json-format.md#2-attributes)部分所述， -CloudEvent 扩展属性与已定义属性(必要属性、可选属性)在序列化时处于同一等级 - -也就是说，它们都是 JSON 对象的顶层属性。 -CloudEvent的作者花了很长时间考虑所有选项，并认为这是最好的选择。 -理由如下： - -由于CloudEvents规范遵循 [semver](https://semver.org/) ， -这意味着只要新属性是可选属性，它们可以在核心规范的未来版本定义，而无需更改当前主要版本。 -在这样的情况下，请考虑现有消费者将如何使用新的（未知的）顶级属性。 -虽然消费者可以随意忽略它，因为它是可选的， -但在大多数情况下，这些属性仍然希望向接收这些事件的应用程序公开。 -这可能导致这些应用程序在基础设施不支持的情况下，支持这些属性。 -这意味着未知的顶级属性（无论是谁定义的——规范的未来版本或事件生产者）可能不会被忽略。 -因此，虽然其它一些规范定义了放置扩展的特定属性（例如顶级`extensions`属性）， -但作者认为在传入事件中具有两个不同位置的未知属性可能会导致互操作性问题和开发人员的混淆。 - -扩展属性通常用于测试那些被规范正式采用之前的潜在属性。 -如果有一个`extensions`类型的属性，这个新属性已经被序列化， -那么如果该属性被核心规范采用，它将从`extensions`属性提升（从序列化的角度）为顶级属性。 -如果我们假设这个新属性是可选的，那么当它被核心规范采用时， -它只是一个小版本增量，所有现有的消费者仍然会继续工作。 -但是，消费者将不知道此属性将出现在何处 - 在扩展属性中还是作为顶级属性。 -这意味着他们可能需要同时查看两个地方。 -如果属性出现在两个地方但具有不同的值怎么办？ -生产者是否需要将它放在两个地方，因为他们可能同时有新、老消费者？ -虽然可以为如何解决出现的每个潜在问题而制定明确的规则， -但作者认为一个避免这些问题的更好的办法是在序列化中只有一个位置来放置未知的甚至是新的属性。 -作者还注意到 HTTP 规范现在遵循类似的模式，不再建议扩展 HTTP 头部以 X- 为前缀。 - -## 生产CloudEvents - -CloudEvents 规范有意避免将CloudEvents 的创建方式设计的过于死板。 -例如，它不假定原始事件源必须是该事件生产对应 CloudEvent 的同一实体。 -这允许多种实现方式。 -但是，对于规范的实现者来说，理解规范作者心中的期望还是有帮助的，因为这将有助于确保互操作性和一致性。 - -如上所述，生成初始事件的实体是否与创建相应 CloudEvent 的实体相同是由实现决定的。 -但是，当构建/填充 CloudEvents 属性的实体代表事件源进行操作时，这些属性的值是用来描述事件或事件源， -而不是计算 CloudEvent 属性值的实体的。 -换句话说，当事件源和 CloudEvents 生产者之间的分离对事件使用者没有实质性意义时， -规范定义的属性通常不会包含任何值来指示这种职责分离。 - -这并不是说 CloudEvents 生产者不能向 CloudEvent 添加一些额外的属性， -但这些属性超出了规范的互操作性定义属性的范围。 -这类似于 HTTP 代理通常如何最大限度地减少对传入消息的明确定义的 HTTP 头部的更改， -但它可能会添加一些额外的头部，其中包括一些特定代理的元数据。 - -还值得注意的是，原始事件源和 CloudEvents 生产者之间的这种分离可大可小。 -意思是，即使 CloudEvent 生产者不是原始事件源生态系统的一部分， -如果它代表事件源行事，并且它在事件流中的存在对事件消费者没有意义，那么上述指导仍然适用。 - -当实体同时充当 CloudEvents 的接收者和发送者以转发或转换传入事件时， -出站 CloudEvent 与入站 CloudEvent 匹配的程度将根据该实体的处理语义而有所不同。 -在它充当代理的情况下，它只是将 CloudEvents 转发给另一个事件消费者， -那么出站 CloudEvent 通常看起来与入站 CloudEvent 就规范定义的属性相同 -- 请参阅上一段有关添加其他属性的内容。 - -但是，如果此实体正在执行 CloudEvent 的某种类型的语义处理， -通常会导致`data`属性值发生更改， -则可能需要将其视为与原始事件源不同的“事件源”。 -因此，与事件生产者相关的 CloudEvents 属性（例如`source` and `id`） -将从传入的 CloudEvent 中更改。 - -## 合格的协议与编码 - -正如规范中所表达的，CloudEvents 工作的明确目标是 -“以通用方式描述事件数据”且 -“定义允许服务产生或消费事件的事件系统的互操作性，其中生产者和消费者可以被独立开发和部署”。 - -这种互操作性的基础是开放的数据格式和协议， -CloudEvents 旨在提供这种开放的数据格式，并将其数据格式映射到常用协议和常用编码上。 - -虽然每个软件或服务产品和项目都可以自己选择自己喜欢的通信形式， -但毫无疑问，这种产品或项目私有的专有协议无法进一步实现跨生产者和消费者的广泛互操作性的目标。 - -特别是在消息传递和事件处理领域，该行业在过去十年中开发出了强大且受到广泛支持的协议 -例如 HTTP 1.1 和 HTTP/2 以及 WebSockets 或 Web 上的事件，或者 MQTT 和 AMQP -用于面向连接的消息传递和遥测传输的协议。 - -一些广泛使用的协议已经成为事实上的标准，这些协议来自三个或更多公司的顶级财团打造的强大生态系统， -还有一些来自单个公司发布的强大项目生态系统，在任何一种情况下都与前面提到的标准栈的演变相一致。 - -CloudEvents的努力不应成为认可或推广项目或产品专有协议的工具， -因为这与CloudEvents 的原始目标背道而驰。 - -要使协议或编码符合核心 CloudEvents 事件格式或协议绑定的条件，它必须属于以下任一类别： - -- 该协议具有广泛认可的多供应商协议标准化机构（例如 W3C、IETF、OASIS、ISO）的正式标准地位 -- 该协议在其生态系统类别中具有“事实上的标准”地位， - 这意味着它被广泛使用，甚至被认为是给定应用程序的标准。 - 实际上，我们希望在供应商中立的开源组织（例如 Apache、Eclipse、CNCF、.NET 基金会）的保护伞下 - 看到至少一个开源实现， - 并且至少有十几个独立供应商在他们的产品中使用它的产品或服务。 - -除了正式状态之外，协议或编码是否符合核心 CloudEvents 事件格式或协议绑定的一个关键标准是， -该组织是否认为协议或编码出现后，该规范对与产品或项目无关的任何一方具有持续的实际利益。 -对此的基本要求是协议或编码的定义方式允许独立于产品或项目代码的替代实现。 - -欢迎将 CloudEvents 的所有其他协议和编码格式 -包含在指向相应项目自己的公共仓库，或站点中的 CloudEvents binding信息的列表中。 - -## 专有的协议与编码 - -为了鼓励更多人采用 CloudEvents，本仓库将自动收集专有协议和编码。 -本仓库的维护人员不负责创建、维护或通知专有规范的维护人员有关专有规范和CloudEvents规范间的偏差。 - -专有规范将托管在他们自己的仓库或文档站点中，并记录在[专有规范](proprietary-specs.md) -文件中。 专有规范应遵循与核心协议和编码相关的其他规范相同的格式。 - -专有规范将比核心规范受到更少的审查，并且随着 CloudEvents 规范的发展， -相应协议和编码的维护者有责任使规范与 CloudEvents 规范保持同步。 -如果专有规范过时太多，CloudEvents 可能会将指向该规范的链接标记为已弃用或将其删除。 - -如果为同一个协议创建了多个不兼容的规范，存储库维护者将不知道哪个规范是正确的，并列出所有规范的链接。 - -## 现有技术 - -本节介绍了工作组在 CloudEvent 规范开发过程中使用的一些输入材料。 - -### 角色 - -下面列举了可能涉及事件的产生、管理或消费的各种参与者和场景。 - -在这些中，事件生产者和事件消费者的角色是不同的。 -单个应用程序上下文背景始终可以同时承担多个角色，包括既是事件的生产者又是事件的消费者。 - -1. 应用程序生成供他人使用的事件， - 如为消费者提供有关终端用户活动、状态变化或环境观察的见解， - 或允许通过事件驱动的扩展来补充应用程序的功能。 +The `id` attribute is meant to be a value that is unique across all events +related to one event source (where each event source is uniquely identified by +its CloudEvents `source` attribute value). While the exact value used is +producer defined, receivers of CloudEvents from a single event source can be +assured that no two events will share the same `id` value. The only exception to +this is if some replay of the event is supported, and in those cases, the `id` +can then be used to detect this. + +Since a single occurrence may result in the generation of more than one event, +in the cases where all of those events are from the same event source, each +CloudEvent constructed will have a unique `id`. Take the example of the creation +of a DB entry, this one occurrence might generate a CloudEvent with a type of +`create` and a CloudEvent with a type of `write`. Each of those CloudEvents +would have a unique `id`. If there is the desire for some correlation between +those two CloudEvents to indicate they are both related to the same occurrence, +then some additional data within the CloudEvent would be used for that purpose. + +In this respect, while the exact value chosen by the event producer might be +some random string, or a string that has some semantic meaning in some other +context, for the purposes of this CloudEvent attribute those meanings are not +relevant and therefore using `id` for some other purpose beyond uniqueness +checking is out of scope of the specification and not recommended. + +## CloudEvent Attribute Extensions + +In order to achieve the stated goals, the specification authors will attempt to +constrain the number of metadata attributes they define in CloudEvents. To that +end, attributes defined by this project will fall into three categories: + +- required +- optional +- extensions + +As the category names imply, "required" attributes will be the ones that the +group considers vital to all events in all use cases, while "optional" ones will +be used in a majority of the cases. Both of the attributes in these cases will +be defined within the specification itself. + +When the group determines that an attribute is not common enough to fall into +those two categories but would still benefit from the level of interoperability +that comes from being well-defined, then they will be placed into the +"extensions" category and put into +[documented extensions](documented-extensions.md). The specification defines how +these extension attributes will appear within a CloudEvent. + +In determining which category a proposed attribute belongs, or even if it will +be included at all, the group uses use-cases and user-stories to explain the +rationale and need for them. This supporting information will be added to the +[Prior Art](#prior-art) section of this document. + +Extension attributes to the CloudEvent specification are meant to be additional +metadata that needs to be included to help ensure proper routing and processing +of the CloudEvent. Additional metadata for other purposes, that is related to +the event itself and not needed in the transportation or processing of the +CloudEvent, should instead be placed within the proper extensibility points of +the event (`data`) itself. + +Extension attributes should be kept minimal to ensure the CloudEvent can be +properly serialized and transported. For example, the Event producers should +consider the technical limitations that might be encountered when adding +extensions to a CloudEvent. For example, the +[HTTP Binary Mode](http-protocol-binding.md#31-binary-content-mode) uses HTTP +headers to transport metadata; most HTTP servers will reject requests with +excessive HTTP header data, with limits as low as 8kb. Therefore, the aggregate +size and number of extension attributes should be kept minimal. + +If an extension becomes popular then the specification authors might consider +moving it into the specification as a core attribute. This means that the +extension mechanism/process can be used as a way to vet new attributes prior to +formally adding them to the specification. + +### JSON Extensions + +As mentioned in the [Attributes](json-format.md#2-attributes) section of the +[JSON Event Format for CloudEvents](json-format.md) specification, CloudEvent +extension attributes are serialized as siblings to the specification defined +attributes - meaning, at the top-level of the JSON object. The authors of the +specification spent a long time considering all options and decided that this +was the best choice. Some of the rationale follows. + +Since the specifications follow [semver](https://semver.org/), this means that +new properties can be defined by future versions of the core specification +without requiring a major version number change - as long as these properties +are optional. In those cases, consider what an existing consumer would do with a +new (unknown) top-level property. While it would be free to ignore it, since it +is optional, in most cases it is believed that these properties would still want +to be exposed to the application receiving those events. This would allow those +applications to support these properties even if the infrastructure doesn't. +This means that unknown top-level properties (regardless of who defined them - +future versions of the spec or the event producer) are probably not going to be +ignored. So, while some other specifications define a specific property under +which extensions are placed (e.g. a top-level `extensions` property), the +authors decided that having two different locations within an incoming event for +unknown properties could lead to interoperability issues and confusion for +developers. + +Often extensions are used to test new potential properties of specifications +prior to them being formally adopted. If there were an `extensions` type of +property, in which this new property was serialized, then if that property were +to ever be adopted by the core specification it would be promoted (from a +serialization perspective) from the `extensions` property to be a top-level +property. If we assume that this new property will be optional, then as it is +adopted by the core specification it will be just a minor version increment, and +all existing consumers should still continue to work. However, consumers will +not know where this property will appear - in the `extensions` property or as a +top-level property. This means they might need to look in both places. What if +the property appears in both place but with different values? Will producers +need to place it in both places since they could have old and new consumers? +While it might be possible to define clear rules for how to solve each of the +potential problems that arise, the authors decided that it would be better to +simply avoid all of them in the first place by only having one location in the +serialization for unknown, or even new, properties. It was also noted that the +HTTP specification is now following a similar pattern by no longer suggesting +that extension HTTP headers be prefixed with `X-`. + +## Creating CloudEvents + +The CloudEvents specification purposely avoids being too prescriptive about how +CloudEvents are created. For example, it does not assume that the original event +source is the same entity that is constructing the associated CloudEvent for +that occurrence. This allows for a wide variety of implementation choices. +However, it can be useful for implementors of the specification to understand +the expectations that the specification authors had in mind as this might help +ensure interoperability and consistency. + +As mentioned above, whether the entity that generated the initial event is the +same entity that creates the corresponding CloudEvent is an implementation +choice. However, when the entity that is constructing/populating the CloudEvents +attributes is acting on behalf of the event source, the values of those +attributes are meant to describe the event or the event source and not the +entity calculating the CloudEvent attribute values. In other words, when the +split between the event source and the CloudEvents producer are not materially +significant to the event consumers, the spec defined attributes would typically +not include any values to indicate this split of responsibilities. + +This isn't to suggest that the CloudEvents producer couldn't add some additional +attributes to the CloudEvent, but those are outside the scope of the +interoperability defined attributes of the spec. This is similar to how an HTTP +proxy would typically minimize changes to the well-defined HTTP headers of an +incoming message, but it might add some additional headers that include +proxy-specific metadata. + +It is also worth noting that this separation between original event source and +CloudEvents producer could be small or large. Meaning, even if the CloudEvent +producer were not part of the original event source's ecosystem, if it is acting +on behalf of the event source, and its presence in the flow of the event is not +meaningful to event consumers, then the above guidance would still apply. + +When an entity is acting as both a receiver and sender of CloudEvents for the +purposes of forwarding, or transforming, the incoming event, the degree to which +the outbound CloudEvent matches the inbound CloudEvent will vary based on the +processing semantics of this entity. In cases where it is acting as proxy, where +it is simply forwarding CloudEvents to another event consumer, then the outbound +CloudEvent will typically look identical to the inbound CloudEvent with respect +to the spec defined attributes - see previous paragraph concerning adding +additional attributes. + +However, if this entity is performing some type of semantic processing of the +CloudEvent, typically resulting in a change to the value of the `data` +attribute, then it may need to be considered a distinct "event source" from the +original event source. And as such, it is expected that CloudEvents attributes +related to the event producer (such as `source` and `id`) would be changed from +the incoming CloudEvent. + +## Qualifying Protocols and Encodings + +The explicit goal of the CloudEvents effort, as expressed in the specification, +is "describing event data in a common way" and "to define interoperability of +event systems that allow services to produce or consume events, where the +producer and consumer can be developed and deployed independently". + +The foundations for such interoperability are open data formats and open +protocols, with CloudEvents aiming to provide such an open data format and +projections of its data format onto commonly used protocols and with commonly +used encodings. + +While each software or service product and project can obviously make its own +choices about which form of communication it prefers, its unquestionable that a +proprietary protocol that is private to such a product or project does not +further the goal of broad interoperability across producers and consumers of +events. + +Especially in the area of messaging and eventing, the industry has made +significant progress in the last decade in developing a robust and broadly +supported protocol foundation, like HTTP 1.1 and HTTP/2 as well as WebSockets or +events on the web, or MQTT and AMQP for connection-oriented messaging and +telemetry transfers. + +Some widely used protocols have become de-facto standards emerging out of strong +ecosystems of top-level consortia of three or more companies, and some out of +the strong ecosystems of projects released by a single company, and in either +case largely in parallel to the evolution of the previously mentioned standards +stacks. + +The CloudEvents effort shall not become a vehicle to even implicitly endorse or +promote project- or product-proprietary protocols, because that would be +counterproductive towards CloudEvents' original goals. + +For a protocol or encoding to qualify for a core CloudEvents event format or +protocol binding, it must belong to either one of the following categories: + +- The protocol has a formal status as a standard with a widely-recognized + multi-vendor protocol standardization body (e.g. W3C, IETF, OASIS, ISO) +- The protocol has a "de-facto standard" status for its ecosystem category, + which means it is used so widely that it is considered a standard for a given + application. Practically, we would like to see at least one open source + implementation under the umbrella of a vendor-neutral open-source organization + (e.g. Apache, Eclipse, CNCF, .NET Foundation) and at least a dozen independent + vendors using it in their products/services. + +Aside from formal status, a key criterion for whether a protocol or encoding +shall qualify for a core CloudEvents event format or protocol binding is +whether the group agrees that the specification will be of sustained practical +benefit for any party that is unrelated to the product or project from which the +protocol or encoding emerged. A base requirement for this is that the protocol +or encoding is defined in a fashion that allows alternate implementations +independent of the product or project's code. + +All other protocol and encoding formats for CloudEvents are welcome to be +included in a list pointing to the CloudEvents binding information in the +respective project's own public repository or site. + +## Proprietary Protocols and Encodings + +To encourage adoption of CloudEvents, this repository will collect CloudEvent +specs for proprietary protocols and encodings without endorsement. Repository +maintainers are not responsible for creating, maintaining, or notifying +maintainers of proprietary specs of drift from the CloudEvents spec. + +Proprietary specs will be hosted in their own repository or documentation site, +and collected in the [proprietary-specs](proprietary-specs.md) file. Proprietary +specs should follow the same format as the other specs for core protocols and +encodings. + +Proprietary specs will receive less scrutiny than a core spec, and as the +CloudEvents spec evolves, it is the responsibility of the maintainers of the +respective protocols and encodings to keep specs in sync with the CloudEvents +spec. If a proprietary spec falls too far out of date, CloudEvents may mark the +link to that spec as deprecated or remove it. + +In the case that multiple, incompatible specs are created for the same protocol, +the repository maintainers will be agnostic about which spec is correct and list +links to all specs. + +## Prior Art + +This section describes some of the input material used by the group during the +development of the CloudEvent specification. + +### Roles + +The list below enumerates the various participants, and scenarios, that might be +involved in the producing, managing or consuming of events. + +In these the roles of event producer and event consumer are kept distinct. A +single application context can always take on multiple roles concurrently, +including being both a producer and a consumer of events. + +1. Applications produce events for consumption by other parties, for instance + for providing consumers with insights about end-user activities, state + changes or environment observations, or for allowing complementing the + application's capabilities with event-driven extensions. + + Events are typically produced related to a context or a producer-chosen + classification. For example, a temperature sensor in a room might be + context-qualified by mount position, room, floor, and building. A sports + result might be classified by league and team. + + The producer application could run anywhere, such as on a server or a device. + + The produced events might be rendered and emitted directly by the producer or + by an intermediary; as example for the latter, consider event data + transmitted by a device over payload-size-constrained networks such as + LoRaWAN or ModBus, and where events compliant to this specification will be + rendered by a network gateway on behalf of the producer. + + For example, a weather station transmits a 12-byte, proprietary event payload + indicating weather conditions once every 5 minutes over LoRaWAN. A LoRaWAN + gateway is then used to publish the event to an Internet destination in the + CloudEvents format. The LoRaWAN gateway is the event producer, publishing on + behalf of the weather station, and will set event metadata appropriately to + reflect the source of the event. + +2. Applications consume events for the purposes such as display, archival, + analytics, workflow processing, monitoring the condition and/or providing + transparency into the operation of a business solution and its foundational + building blocks. + + The consumer application could run anywhere, such as on a server or a device. + + A consuming application will typically be interested in: + + - distinguishing events such that the exact same event is not processed + twice. + - identifying and selecting the origin context or the producer-assigned + classification. + - identifying the temporal order of the events relative to the originating + context and/or relative to a wall-clock. + - understanding the context-related detail information carried in the event. + - correlating event instances from multiple event producers and send them to + the same consumer context. + + In some cases, the consuming application might be interested in: + + - obtaining further details about the event's subject from the originating + context, like obtaining detail information about a changed object that + requires privileged access authorization. For example, a HR solution might + only publish very limited information in events for privacy reasons, and + any event consumer needing more data will have to obtain details related to + the event from the HR system under their own authorization context. + - interact with the event's subject at the originating context, for instance + reading a storage blob after having been informed that this blob has just + been created. + + Consumer interests motivate requirements for which information producers + ought to include an event. + +3. Middleware routes events from producers to consumers, or onwards to other + middleware. Applications producing events might delegate certain tasks + arising from their consumers' requirements to middleware: + + - Management of many concurrent interested consumers for one of multiple + classes or originating contexts of events + - Processing of filter conditions over a class or originating context of + events on behalf of consumers. + - Transcoding, like encoding in MsgPack after decoding from JSON + - Transformation that changes the event's structure, like mapping from a + proprietary format to CloudEvents, while preserving the identity and + semantic integrity of the event. + - Instant "push-style" delivery to interested consumers. + - Storing events for eventual delivery, either for pick-up initiated by the + consumer ("pull") or initiated by the middleware ("push") after a delay. + - Observing event content or event flow for monitoring or diagnostics + purposes. + + To satisfy these needs, middleware will be interested in: + + - A metadata discriminator usable for classification or contextualization of + events so that consumers can express interest in one or multiple such + classes or contexts. For instance, a consumer might be interested in all + events related to a specific directory inside a file storage account. + - A metadata discriminator that allows distinguishing the subject of a + particular event of that class or context. For instance, a consumer might + want to filter out all events related to new files ending with ".jpg" (the + file name being the "new file" event's subject) for the context describing + specific directory inside a file storage account that it has registered + interest on. + - An indicator for the encoding of the event and its data. + - An indicator for the structural layout (schema) for the event and its data. + + Whether its events are available for consumption via a middleware is a + delegation choice of the producer. + + In practice, middleware can take on the role of a + [Producer](spec.md#producer) when it changes the semantic meaning of an + event, a [Consumer](spec.md#consumer) when it takes action based on an event, + or [Intermediary](spec.md#intermediary) when it routes events without making + semantic changes. + +4. Frameworks and other abstractions make interactions with event platform + infrastructure simpler, and often provide common API surface areas for + multiple event platform infrastructures. + + Frameworks are often used for turning events into an object graph, and to + dispatch the event to some specific handling user-code or user-rule that + permits the consuming application to react to a particular kind of occurrence + in the originating context and on a particular subject. + + Frameworks are most interested in semantic metadata commonality across the + platforms they abstract, so that similar activities can be handled uniformly. + + For a sports application, a developer using the framework might be interested + in all events from today's game (subject) of a team in a league (topic of + interest) but wanting to handle reports of "goal" differently than reports of + "substitution". For this, the framework will need a suitable metadata + discriminator that frees it from having to understand the event details. + +### Value Proposition + +This section describes some of the use-cases that explain the value of +CloudEvents. + +#### Normalizing Events Across Services & Platforms + +Major event publishers (e.g. AWS, Microsoft, Google, etc.) all publish events in +different formats on their respective platforms. There are even a few cases +where services on the same provider publish events in different formats (e.g. +AWS). This forces event consumers to implement custom logic to read or munge +event data across platforms and occasionally across services on a single +platform. + +CloudEvents can offer a single experience for authoring consumers that handle +events across all platforms and services. + +#### Facilitating Integrations Across Services & Platforms + +Event data being transported across environments is increasingly common. +However, without a common way of describing events, delivery of events across +environments is hindered. There is no single way of determining where an event +came from and where it might be going. This prevents tooling to facilitate +successful event delivery and consumers from knowing what to do with event data. + +CloudEvents offers useful metadata which middleware and consumers can rely upon +to facilitate event routing, logging, delivery and receipt. + +#### Increasing Portability of Functions-as-a-Service + +Functions-as-a-Service (also known as serverless computing) is one of the +fastest growing trends in IT and it is largely event-driven. However, a primary +concern of FaaS is vendor lock-in. This lock-in is partially caused by +differences in function APIs and signatures across providers, but the lock-in is +also caused by differences in the format of event data received within +functions. - 生产的事件通常与上下文或生产者选择的分类相关。 - 例如，房间中的温度传感器可能被安装位置、房间、楼层和建筑物等上下文限定。 - 运动结果可以按联赛和球队分类。 +CloudEvents' common way of describing event data increases the portability of +Functions-as-a-Service. - 生产者应用程序可以在任何地方运行，例如在服务器或设备上。 +#### Improving Development & Testing of Event-Driven/Serverless Architectures + +The lack of a common event format complicates development and testing of +event-driven and serverless architectures. There is no easy way to mock events +accurately for development and testing purposes, and help emulate event-driven +workflows in a development environment. + +CloudEvents can enable better developer tools for building, testing and handling +the end-to-end lifecycle of event-driven and serverless architectures. - 生产的事件可能由生产者或中间人直接提供和发出； - 作为后者的示例，请考虑设备通过负载大小受限的网络（如 LoRaWAN 或 ModBus）传输的事件数据， - 并且符合此规范的事件将由网络网关代表生产者提供。 +#### Event Data Evolution - 例如，气象站每 5 分钟通过 LoRaWAN 传输一次 12 字节的专有事件payload用于指示天气状况。 - 然后使用 LoRaWAN 网关以 CloudEvents 格式将事件发布到 Internet 目标。 - LoRaWAN 网关是事件生产者，代表气象站发布事件，并将设置一定的元数据以反映事件的来源(气象站)。 +Most platforms and services version the data model of their events differently +(if they do this at all). This creates an inconsistent experience for publishing +and consuming the data model of events as those data models evolve. -2. 应用程序可能以以下目的： - 如显示、存档、分析、工作流处理、监控状态或提供业务解决方案及其基本构建模块的透明化 - 来消费事件。 +CloudEvents can offer a common way to version and evolve event data. This will +help event publishers safely version their data models based on best practices, +and this help event consumers safely work with event data as it evolves. - 消费者应用程序可以在任何地方运行，例如在服务器或设备上。 +#### Normalizing Webhooks - 消费应用程序通常对以下内容感兴趣： +Webhooks is a style of event publishing which does not use a common format. +Consumers of webhooks don’t have a consistent way to develop, test, identify, +validate, and overall process event data delivered via webhooks. - - 区分事件，使得完全相同的事件不会被处理两次。 - - 识别和选择源上下文或生产者指定的分类。 - - 确定事件相对于原始上下文或相对于时钟的时间顺序。 - - 了解事件中携带的上下文相关的详细信息。 - - 关联来自多个事件生产者的事件实例并将它们发送到相同的消费者上下文。 +CloudEvents can offer consistency in webhook publishing and consumption. - 在某些情况下，消费应用程序可能对以下内容感兴趣： +#### Policy Enforcement - - 从原始上下文中获取有关事件主题的更多详细信息，例如获取有关需要特权访问授权的已更改对象的详细信息。 - 例如，出于隐私原因，HR 解决方案可能仅在事件中发布非常有限的信息， - 任何需要更多数据的事件消费者都必须在其自己的授权上下文背景下从 HR 系统获取与事件相关的详细信息 - - 在原始上下文中与事件的主题进行交互，例如在被告知该数据块刚刚创建后读取存储该数据块。 +The transiting of events between systems may need to be filtered, transformed, +or blocked due to security and policy concerns. Examples may be to prevent +ingress or egress of the events such as event data containing sensitive +information or wanting to disallow the information flow between the sender and +receiver. - 消费者的兴趣激发了信息生产者应该包括事件的需求。 +A common event format would allow easier reasoning about the data being +transited and allow for better introspection of the data. -3. 中间件将事件从生产者路由到消费者，或转发到其他中间件。 - 产生事件的应用程序可能会将根据消费者需求产生的某些任务委托给中间件： +#### Event Tracing - - 管理同时对大量类别和上下文背景中的某个事件感兴趣的消费者。 - - 代表消费者在类或事件的原始上下文上处理过滤条件。 - - 转码，比如从 JSON 解码后在 MsgPack 中编码。 - - 更改事件结构的转换，例如从专有格式映射到 CloudEvents，同时保留事件的身份和语义完整性。 - - 即时“推送式”传输给感兴趣的消费者。 - - 存储最终传输的事件，用于由消费者发起的“拉”请求，或延迟后由中间件发起“推”请求。 - - 观察事件内容或事件流以进行监控或诊断。 - - 为了满足这些需求，中间件将对以下方面感兴趣： - - - 一种元数据鉴别器，可用于事件的分类或上下文化，以便消费者可以表达对一个或多个类或上下文的兴趣。 - 例如，消费者可能对文件存储帐户内的特定目录相关的所有事件感兴趣。 - - 一种元数据鉴别器，允许区分该类或上下文的特定事件的主题。例如，消费者可能希望过滤掉与以“.jpg”结尾的 - 新文件相关的所有事件（文件名是“新文件”事件的主题），以此表示它对感兴趣的文件存储账户下某个目录的 - 上下文环境。 - - 一个事件及其数据编码的指示器。 - - 一个事件及其数据的结构布局（模式）的指示器。 - - 事件是否可通过中间件消费取决于生产者的选择。 - - 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec.md#生产者)的角色， - 当它根据事件采取行动时可以扮演[消费者](spec.md#消费者)的角色， - 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec.md#中间人)的角色。 - -4. 框架和其他抽象使与事件平台基础设施间的交互更简单， - 并且通常为多个事件平台基础设施提供公共 API 区域。 - - 框架通常用于将事件转换为对象图，并将事件分派给某些特定的处理逻辑或用户规则， - 这些用户逻辑或用户规则允许消费应用程序对原始上下文和特定主题中的特定类型的事件做出反应。 - - 框架最感兴趣的是跨抽象平台的语义元数据通用性，以便可以统一处理类似的活动。 - - 对于体育应用程序，使用该框架的开发人员可能对联盟中一支球队今天的比赛（主题） - 的所有事件感兴趣，但希望以不同于“换人”事件的方式处理“得分”事件。 - 为此，框架将需要一个合适的元数据鉴别器，使其不必了解事件细节。 - -### 价值主张 - -本节介绍了一些能够展示 CloudEvents 价值主张的用例。 - -#### 跨服务和平台规范化事件 - -主要事件发布者（例如 AWS、Microsoft、Google 等）都在各自的平台上以不同的格式发布事件。 -甚至在少数情况下，同一提供商的服务以不同格式（例如 AWS）发布事件。 -这迫使事件消费者实现自定义逻辑以跨平台读取或处理事件数据，有时甚至需要跨单个平台的多个服务处理。 - -CloudEvents 可以为那些跨平台和服务处理事件的使用者提供单一体验。 - -#### 促进跨服务和平台的集成 - -跨环境传输的事件数据越来越普遍。 -然而，如果没有描述事件的通用方式，跨环境的事件传递就会受到阻碍。 -CloudEvents之前没有单一的方法可以确定事件的来源和可能的去向。 -这对研究成功传输事件事件工具和消费者知道如何处理事件数据形成了巨大阻碍。 - -CloudEvents 提供有用的元数据，中间件和消费者可以依赖这些元数据来促进事件路由、日志记录、传输和接收。 - -#### 提高功能即服务的可移植性 - -功能即服务（也称为serverless计算）是 IT 中增长最快的趋势之一，它主要是由事件驱动的。 -然而，FaaS 的一个主要问题是供应商锁定。 -这种锁定部分是由函数 API 和供应商之间签名的差异引起的， -锁定同样也是由函数内接收的事件数据格式的差异引起的。 - -CloudEvents提供描述事件数据的通用方式提高了功能即服务的可移植性。 - -#### 改进事件驱动/serverless架构的开发和测试 - -缺乏通用事件格式使事件驱动和serverless架构的开发和测试变得复杂。 -没有简单的方法可以准确地为开发和测试目的模拟事件，并帮助在开发环境中模拟事件驱动的工作流。 - -CloudEvents 可以提供更好的开发工具来构建、测试和处理事件驱动和无服务器架构的端到端生命周期。 - -#### 事件数据发展 - -大多数平台和服务对其事件的数据模型进行不同的版本控制（如果他们这样做的话）。 -随着这些数据模型的发展，这会为发布和使用事件的数据模型带来不一致的体验。 - -CloudEvents 可以提供一种通用的方式来版本化和演化事件数据的发展。 -这将帮助事件发布者根据最佳实践安全地对其数据模型进行版本控制， -并且这有助于事件消费者随着事件数据的发展安全地使用它。 - -#### 规范化 Webhook - -Webhooks 是一种不使用通用格式的来发布事件的模式。 -Webhook 的使用者没有一致的方式来开发、测试、识别、验证和整体处理通过 Webhook 传输的事件数据。 - -CloudEvents 可以提供 Webhook 发布和消费事件的一致性。 - -#### 安全策略 - -出于安全和策略考虑，可能需要过滤、转换或阻止系统之间的事件传输。 -比如可能需要防止事件的进入或退出，如包含敏感信息的事件数据或想要禁止发送方和接收方之间的信息流。 - -通用事件格式将允许更容易地推理正在传输的数据，并提供更好的数据自查。 - -#### 事件追踪 - -从源发送的事件可能会出现在一系列附加事件序列之中， -这些附加事件序列从各种中间件设备（例如事件代理和网关）发出。 -CloudEvents 在事件中包含元数据以将这些事件关联为事件序列的一部分，以便进行事件跟踪和故障排除。 +An event sent from a source may result in a sequence of additional events sent +from various middleware devices such as event brokers and gateways. CloudEvents +includes metadata in events to associate these events as being part of an event +sequence for the purpose of event tracing and troubleshooting. #### IoT -物联网设备会发送和接收与其功能相关的事件。 -例如，连接的恒温器将发送有关当前温度的遥测数据， -并可以接收改变温度的事件。 -这些设备通常具有受限的操作环境（cpu、内存），需要明确定义的事件消息格式。 -在很多情况下，这些消息是二进制编码的，而不是文本的。 -无论是直接来自设备还是通过网关转换，CloudEvents 都可以更好地描述消息的来源和消息中包含的数据格式。 - -#### 事件关联 - -一个serverless应用或工作流可能与来自不同事件源或事件生产者的多个事件相关联。 -例如，盗窃检测应用程序/工作流可能涉及运动事件和门/窗打开事件。 -一个serverless平台可能接收每种类型事件的许多实例，例如 它可以接收来自不同房屋的运动事件和开窗事件。 - -serverless平台需要将一种类型的事件实例与其他类型的事件实例正确关联， -并将接收到的事件实例映射到正确的应用/工作流实例。 -CloudEvents 将为任何事件使用者（例如serverless平台）提供一种标准方式， -以在事件数据中定位事件关联信息/令牌并将接收到的事件实例映射到正确的应用/工作流实例。 - -### 现有的数据格式 - -与上一节一样，对当前现状的调查（和理解）对CloudEvents 小组来说非常重要。 -为此，下面列出了在实践中被广泛使用的当前事件格式的样本。 +IoT devices send and receive events related to their functionality. For example, +a connected thermostat will send telemetry on the current temperature and could +receive events to change temperatures. These devices typically have a +constrained operating environment (cpu, memory) requiring a well-defined event +message format. In a lot of cases these messages are binary encoded instead of +textual. Whether directly from the device or transformed via a gateway, +CloudEvents would allow for a better description of the origin of the message +and the format of the data contained within the message. + +#### Event Correlation + +A serverless application/workflow could be associated with multiple events from +different event sources/producers. For example, a burglary detection +application/workflow could involve both a motion event and a door/window open +event. A serverless platform could receive many instances of each type of +events, e.g. it could receive motion events and window open events from +different houses. + +The serverless platform needs to correlate one type of event instance correctly +with other types of event instances and map a received event instance to the +correct application/workflow instance. CloudEvents will provide a standard way +for any event consumer (e.g. the serverless platform) to locate the event +correlation information/token in the event data and map a received event +instance to the correct application/workflow instance. + +### Existing Event Formats + +As with the previous section, the examination (and understanding) of the current +state of the world was very important to the group. To that end, a sampling of +existing current event formats that are used in practice today was gathered. #### Microsoft - Event Grid @@ -588,7 +780,8 @@ CloudEvents 将为任何事件使用者（例如serverless平台）提供一种 #### AWS - CloudWatch Events -AWS 上的很大一部分事件处理系统都在使用这种格式。 +A high proportion of event-processing systems on AWS are converging on the use +of this format. ``` { From 0408dd0beeee8b601eaa73b37aece36ffe52e59c Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:28:25 +0800 Subject: [PATCH 20/60] Create spec_CN.md --- spec_CN.md | 478 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 478 insertions(+) create mode 100644 spec_CN.md diff --git a/spec_CN.md b/spec_CN.md new file mode 100644 index 000000000..7c9c1a8cd --- /dev/null +++ b/spec_CN.md @@ -0,0 +1,478 @@ +# CloudEvents 核心规范- 1.0 版本 + +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. + +## 摘要 + +CloudEvents 是一个用于定义事件格式的供应商中立规范。 + +## 目录 + +- [概览](#概览) +- [符号和术语](#符号和术语) +- [上下文属性](#上下文属性) +- [事件数据](#事件数据) +- [大小限制](#大小限制) +- [隐私与安全](#隐私与安全) +- [示例](#示例) + +## 概览 + +事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 + +对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。 +它同样限制了那些用来帮助事件数据完成 跨环境传输的库(如SDKs)， +工具(如事件路由器)和基础设施(如事件追踪系统)的发展。 +总体来看，这种匮乏严重阻碍了事件数据的可移植性和生产力。 + +CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 + +事件格式指定如何使用某些编码格式序列化一个 CloudEvent。 +支持那些编码且兼容 CloudEvents 的实现必须遵守相应事件格式中指定的编码规则。 +所有实现都必须支持 [JSON 格式](json-format.md)。 + +有关规范背后的历史、开发和设计原理等更多信息， +请参阅 CloudEvents [入门文档](primer.md)。 + +## 符号和术语 + +### 符号约定 + +本文档中的关键词 +"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 需要按照 +[RFC 2119](https://tools.ietf.org/html/rfc2119) 中的描述来理解。 + +为清楚起见， +当一个功能被标记为“OPTIONAL”时，这意味着消息的 +[生产者](#生产者)和[消费者](#消费者) 都可以自行选择是否支持该功能。 +换句话说，生产者可以在需要时在消息中包含该功能，消费者也可以在需要时选择支持该功能。 +不支持该功能的消费者将默默地忽略该部分消息。 +生产者需要做好消费者并没有启用该功能的准备。 +[中间人](#中间人) 应当转发OPTIONAL属性。 + +### 术语 + +本规范定义了下列术语 + +#### 发生 + +“发生”是指在软件系统运行期间对事实状态的捕获。 +这可能是由于系统发出了信号或系统观察到信号、状态更改、计时器超时 +或任何其他值得注意的活动而发生的。 +例如，设备可能会因为电池电量低或虚拟机即将执行计划的重启而进入警报状态。 + +#### 事件 + +“事件”是表示一条"发生"及其上下文的数据记录。 +事件从事件生产者（源）路由到对它感兴趣的事件消费者。 +事件中包含的信息帮助完成路由操作，但事件不会标识特定的路由目的地。 +事件将包含两种类型的信息：表示"发生"的 [事件数据](#事件数据) +和提供有关事件的环境信息的[上下文](#上下文) 元数据。 +一次"发生"可能导致多个事件的产生。 + +#### 生产者 + +“生产者”是一种特定的实例、进程或设备，它能够创建用来描述CloudEvent的数据结构。 + +#### 源 + +"源"是事件发生的上下文环境。在分布式系统中，它可能由多个生产者组成。 +如果一个源无法查看到CloudEvents，那么一定有有外部的生产者在代替源来生产CloudEvent。 + +#### 消费者 + +一个“消费者”会接收事件并根据事件采取一定的行为。 +它使用上下文环境和事件数据来执行一些逻辑，这可能会导致新事件的发生。 + +#### 中间人 + +一个“中间人”会接收包含事件的消息， +并将其转发给下一个接收者，但该接收者可能是另一个中间人或事件[消费者](#消费者)。 +中间人的典型任务就是根据[上下文](#上下文)环境中的信息将事件路由到接收者。 + +#### 上下文 + +上下文环境元数据被封装在[上下文-属性](#上下文-属性)中。 +工具和应用程序代码可以使用此信息来识别事件与系统方面或事件与其他事件的关系。 + +#### 数据 + +关于事件的特定域信息（即有效负载）。这可能包括有关事件的信息、有关已更改数据的详细信息等。 +有关更多信息，请参阅[事件数据](#事件数据)部分。 + +#### 事件格式 + +一个事件格式会指定如何将 CloudEvent 序列化为字节序列。 +独立事件格式（例如 [JSON 格式](json-format.md)）指定独立于任何协议或存储介质的序列化。 +协议绑定可以定义依赖于协议的格式。 + +#### 消息 + +事件通过消息从源传输到目标。 + +“结构化模式消息”是一种使用独立事件格式对事件进行完全编码并存储在消息体中的消息。 + +“二进制模式消息”会将事件数据存储在消息体中，并将事件属性作为消息元数据的一部分存储下来。 + +#### 协议 + +消息可以通过各种行业标准协议 +（例如 HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或平台/供应商 +专有协议（AWS Kinesis、Azure 事件网格）传输。 + +#### 协议绑定 + +协议绑定描述了如何通过给定协议发送和接收事件，特别是如何将事件映射到该协议的消息中去。 + +## 上下文属性 + +每个符合本规范的 CloudEvent 必须包括指定为 REQUIRED 的上下文属性， +可以包括一个或多个OPTIONAL上下文属性， +并且可以包括一个或多个扩展属性。 + +这些属性虽然描述了事件，但被设计为可以独立于事件数据进行序列化。 +这允许在不反序列化事件数据的情况下，在目的检查这些上下文属性。 + +### 属性命名约定 + +CloudEvents 规范定义了到各种协议和编码的映射，随附的 CloudEvents SDK 面向各种运行时和编程语言。 +其中一些将元数据元素区分大小写，而另一些则不区分， +并且单个 CloudEvent 可能通过涉及到协议、编码和运行时混合的多个跃点进行路由。 +因此，本规范限制了所有属性的可用字符集，以防止区分大小写问题或与通用语言中标识符的合法字符集冲突问题。 + +CloudEvents 属性名称必须由来自 ASCII 字符集的小写字母（“a”到“z”）或数字（“0”到“9”）组成。 +属性名称应该是描述性的和简洁的，并且长度不应超过 20 个字符。 + +### 类型系统 + +以下抽象数据类型可用于属性。 +这些类型中的每一种都可以由不同的事件格式和协议元数据字段以不同的方式表示。 +本规范为所有实现必须支持的每种类型定义了规范的字符串编码。 + +- `Boolean` - “true”或“false”的布尔值。 + - 字符串编码：区分大小写的`true` 或 `false`值。 +- `Integer` -范围在 -2,147,483,648 到 +2,147,483,647 （包含）之间的整数。 + 这是有符号 32 位二进制补码编码的范围。 + 事件格式不必使用此编码，但它们必须使用在此范围内的`Integer` 值。 + - 字符串编码: 符合 + [RFC 7159, 第 6 节](https://tools.ietf.org/html/rfc7159#section-6) + JSON 数字的整数部分 +- `String` - 允许的 Unicode 字符序列。 不允许使用以下字符： + - 范围 U+0000-U+001F 和 U+007F-U+009F（包含首尾）中的“控制字符”， + 因为大多数没有商定的含义，还有一些，例如 U+000A（换行符）， 在如 HTTP 头部之类的上下文中不可用。 + -[被 Unicode 标识为非字符的](http://www.unicode.org/faq/private_use.html#noncharacters) + 代码点。 + - 被 Unicode 标识为代理项的代码点, 范围 U+D800-U+DBFF 和 U+DC00-U+DFFF（包含首尾） + , 除非被合理的用作代理对. 因此（在 JSON 符号中） + “\uDEAD”是无效的，因为它是一个未配对的代理，而“\uD800\uDEAD”是合法的。 +- `Binary` - 字节序列. + - 字符串编码: 基于 + [RFC4648](https://tools.ietf.org/html/rfc4648) 的Base64 编码。 +- `URI` - 绝对统一资源标识符。 + - 字符串编码: + [RFC 3986 第 4.3 节](https://tools.ietf.org/html/rfc3986#section-4.3) + 中定义的 `Absolute URI` 。 +- `URI-reference` - 统一资源标识符引用。 + - 字符串编码: + [RFC 3986 第 4.1 节](https://tools.ietf.org/html/rfc3986#section-4.1) + 中定义的`URI-reference` 。 +- `Timestamp` - 使用公历的日期和时间表达式。 + - 字符串编码: [RFC 3339](https://tools.ietf.org/html/rfc3339) 。 + +所有上下文属性值必须是上面列出的类型之一。 +属性值可以表示为原生类型或规范字符串。 + +当强类型编程语言表示 CloudEvent 或任何扩展时， +必须能够在规范字符串编码与对应抽象类型的运行时/编程语言类型之间进行转换。 + +例如，在给定的实现中，`time` 属性可能由编程语言的本地时间类型表示， +但它必须是可设置提供 RFC3339 字符串的， +并且当映射到 HTTP 消息头时，它必须可转换为 RFC3339 字符串。 + +CloudEvents 协议绑定或事件格式实现同样必须能够 +在规范字符串编码与协议元数据字段中的对应数据类型之间进行转换。 + +`Timestamp` 类型的属性值确实可能以字符串形式路由通过多个跃点， +并且仅在生产者和最终消费者处实现为本地运行时/语言类型。 +`Timestamp` 类型也可以作为本机协议类型路由， +并且可以在生产者和消费者端映射到/从各自的语言/运行时类型，但永远不会转为字符串格式。 + +序列化机制的选择将决定上下文属性和事件数据将如何序列化。 +例如，在 JSON 序列化的情况下，上下文属性和事件数据可能都出现在同一个 JSON 对象中。 + +### 必要属性 + +下列属性必须自所有的 CloudEvents 中展示： + +#### id + +- 类型: `String` +- 描述: 标识一个事件。 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 + 如果重复的事件被重新发送（例如由于网络错误），它可能具有相同的 `id`。 + Consumers MAY assume that + 消费者可以假设具有相同`source` 和 `id`的事件是重复的。 +- 示例: + - 一个由生产者维护的事件计数器 + - 一个 UUID +- 约束条件: + - 必要的 + - 必须是非空字符串 + - 在生产者的范围内必须是唯一的 + +#### source + +- 类型: `URI-reference` +- 描述: 标识事件发生的上下文背景。 这通常包括诸如事件源类型、发布事件的组织 + 或产生事件的过程等信息。URI 中编码的数据背后的确切语法和语义由事件生产者定义。 + + 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 + + 应用程序可以为每个不同的生产者分配一个唯一的`source`， + 这使得生成唯一 ID 变得容易，因为没有其他生产者将拥有相同的来源。 + 应用程序可以使用 UUIDs、URNs、DNS权威机构或特定于应用程序的方案来创建唯一的`source` 标识符。 + + 一个来源可以包括多个生产者。 + 在这种情况下，生产者必须协作以确保每个不同事件的 `source` + `id`都是唯一的。 + +- 约束条件: + - 必要的 + - 必须是非空 URI-reference + - 推荐使用 绝对 URI +- 示例 + - 具有 DNS 权限的 Internet 范围唯一 URI： + - https://github.com/cloudevents + - mailto:cncf-wg-serverless@lists.cncf.io + - 具有 UUID 的通用唯一 URN： + - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 + - 应用程序专有的标识符 + - /cloudevents/spec/pull/123 + - /sensors/tn-1234567/alerts + - 1-555-123-4567 + +#### specversion + +- 类型: `String` +- 描述: 事件使用的 CloudEvents 规范的版本。 + 这让解释上下文环境更容易。 + 当引用这个版本的规范时，兼容的事件生产者必须使用 `1.0` 的值。 +- 约束条件: + - 必要的 + - 必须是非空字符串 + +#### type + +- 类型: `String` +- 描述: 该属性包含一个值，描述与原始事件相关的事件类型。 + 该属性通常用于路由、可观察性、策略实施等。其格式是生产者定义的，可能包括诸如 `type`版本之类的信息 + -从 + [入门文档-属性版本控制](primer.md#属性版本控制) 中获得更多信息 + +- 约束条件: + - 必要的 + - 必须是非空字符串 + - 应该以反向 DNS 名称作为前缀。该前缀域表明了定义此事件类型语义的组织。 +- 示例 + - com.github.pull.create + - com.example.object.delete.v2 + +### 可选属性 + +下列属性在 CloudEvents 中是可选的. 在 +[符号约定](#notational-conventions) 中查看更多 OPTIONAL 定义的信息。 + +#### datacontenttype + +- 类型: `String` [RFC 2046](https://tools.ietf.org/html/rfc2046) +- 描述: `data`值的内容类型。 此属性使`data`能够承载任何类型的内容， + 因此格式和编码可能与所选事件格式的不同。 + 例如，使用 [JSON envelope](./json-format.md#3-envelope) + 格式呈现的事件可能在数据中携带 XML 的payload，这个属性可以用来通知消费者 + 设置"application/xml"。 + 关于`data`内容如何提供不同的`datacontenttype`的值的规则在事件格式规范中定义。 + 例如，JSON 事件格式定义了 [3.1 节](./json-format.md#31-handling-of-data)中的关系。 + 对于某些二进制模式协议绑定， + 此字段直接能映射到相应协议的内容类型的元数据属性上。 + 二进制模式和内容类型元数据映射的规范规则可以在各自的协议中找到。 + + 在某些事件格式中，可以省略 `datacontenttype` 属性。 + 例如，如果 JSON 格式的事件没有 `datacontenttype` 属性， + 则表示该`data`是符合“application/json”媒体类型的 JSON 值。 + 换句话说：一个没有 `datacontenttype` 的 JSON 格式的事件完全等同于 + 一个带有 `datacontenttype="application/json"`的事件。 + + 当将没有 `datacontenttype` 属性的事件消息转换为不同的格式或协议绑定时， + 目标 `datacontenttype` 应该显式设置为事件源的隐含或默认的 `datacontenttype`。 + +- 约束条件: + - 可选的 + - 若有则必须遵守 + [RFC 2046](https://tools.ietf.org/html/rfc2046) 制定的格式 +- 媒体类型示例 + [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml) + +#### dataschema + +- 类型: `URI` +- 描述: 标识 `data` 遵守的规范。 对模式的不兼容的更改应该由不同的 URI 体现。 在 + [入门文档-属性版本控制](primer.md#属性版本控制) + 中查看更多信息。 +- 约束条件: + - 可选的 + - 若有必须是非空的 URI + +#### subject + +- 类型: `String` +- 描述: 这个属性描述了事件生产者 (由`source`标识) 上下文环境中的主题信息。 + 在发布-订阅场景中，订阅者通常会订阅`source`发出的事件， + 但如果`source` 的上下文环境具有内部子结构， + 则单独的`source`标识符可能不足以作为任何指定事件的限定符。 + + 在上下文元数据中识别事件的主题（与仅在数据负载中相反） + 对于中间件无法解释`data` 内容的通用订阅过滤场景特别有用。 + 在上面的示例中，订阅者可能只对名称以“.jpg”或“.jpeg”结尾的blob感兴趣， + 此时`subject` 属性允许为该事件子集构建简单有效的字符串后缀过滤器。 + +- 约束条件: + - 可选的 + - 若有必须是非空字符串 +- 示例: + - 订阅者可能对在blob在blob存储容器中创建的时候感兴趣并订阅。 + 在这个场景下，事件`source`标示出订阅的范围（存储容器），`type` 标识出 + blob 创建" 这个事件，`id` 唯一标识出事件示例，以区分已创建同名blob的事件， + 而新创建的blob的名字可以放在`subject`属性中： + - `source`: https://example.com/storage/tenant/container + - `subject`: mynewfile.jpg + +#### time + +- 类型: `Timestamp` +- 描述: 事件发生的时间戳。 + 如果无法确定发生的时间，则 CloudEvents 生产者可以将此属性设置为其他时间（例如当前时间）。 + 但是在这方面，同一`source`的所有生产者必须保持一致。 + 换句话说，要么它们都使用发生的实际时间，要么它们都使用相同的算法来确定所使用的值。 + +- 约束条件: + - 可选的 + - 若有则必须遵守 + [RFC 3339](https://tools.ietf.org/html/rfc3339) + +### 扩展上下文属性 + +CloudEvent 可以包含任意数量的具有不同名称的附加上下文属性，被称为"扩展属性"。 +扩展属性必须遵循相同的[命名约定](#属性命名约定)并使用与标准属性相同的 +[类型系统](#类型系统)。 +扩展属性在本规范中没有定义好的含义， +它们允许外部系统将元数据附加到事件，就像 HTTP 自定义头部一样。 + +扩展属性总是如标准属性一样，根据绑定规则进行序列化。 +然而，该规范不阻止扩展将事件属性值复制到消息的其他部分， +以便与也其它处理消息的非 CloudEvents 系统进行交互。 +如果复制的值与云事件序列化值不同，执行此操作的扩展规范应该指定接收者如何解释消息。 + +#### 定义扩展 + +在 +[CloudEvent-属性扩展](primer.md#CloudEvent-属性扩展) +查阅有关扩展使用和定义等相关信息。 + +扩展的定义应该完全定义属性的方方面面——例如 它的名称、类型、语义含义和可能的值。 +新的扩展定义应该使用一个足够描述性的名称来减少与其他扩展的名称冲突的机会。 +特别是，扩展作者应该检查[扩展文件](documented-extensions.md)中 +已知的扩展集——不仅是可能的名称冲突，还有相同目的冲突的扩展。 + +许多协议为发送者提供了包含额外元数据的能力，例如作为 HTTP 头部。 +虽然没有强制要求 CloudEvents 接受者处理和传递它们， +但建议接受者通过某种机制进行处理，以明确它们是非 CloudEvents 的元数据。 + +下面是一个示例，说明了 CloudEvents 对附加属性的需求。 +在许多物联网和企业用例中，事件可用于跨多种类型事件执行操作的serverless应用程序中。 +为了支持这样的用例，事件生产者需要向“上下文属性”添加额外的身份属性， +事件消费者可以使用这些属性将这个事件与其他事件相关联。 +如果此类身份属性恰好是事件“数据”的一部分， +则事件生产者还会将身份属性添加到“上下文属性”中， +以便事件消费者可以轻松访问此信息，而无需解码和检查事件数据。 +此类身份属性还可用于帮助中间网关确定如何路由事件。 + +## 事件数据 + +正如[数据](#数据)所定义的那样，CloudEvents 可以包括有关事件的特定域的信息。 +这些信息将被封装在`data`中。 + +- 描述: 事件负载。 本规范对该信息的类型不作任何限制。 + 它被编码为一种媒体格式，这种格式由`datacontenttype` 属性(如 application/json)指定， + 并在存在这些相应属性时遵循`dataschema`格式。 + It is encoded into a media format + +- 约束条件: + - 可选的 + +# 大小限制 + +在很多情况下，CloudEvents 将通过一个或多个通用中间人进行转发， +每个中间人都可能对转发事件的大小施加限制。 +CloudEvents 也可能直接被路由到消费者，如嵌入式设备， +这些设备是受存储或内存限制的，对单个大型事件表现不佳。 + +事件的“大小”是它的线路大小，包括在线路上为事件传输的每一位： +协议帧元数据、事件元数据和事件数据，基于所选的事件格式和所选的协议绑定。 + +如果应用程序配置需要跨不同协议路由事件或重新编码事件， +应用程序能使用的效率最低的协议和编码，都修腰符合这些大小限制： + +- 中间人转发的事件大小必须为 64 KB 或更小。 +- 消费者应该能接受大小至少为 64 KB 的事件。 + +为了方便，上述规则将允许生产者安全地发布最大 64KB 的事件。 +这里的安全意味着生产者期望事件被所有中间人接受并合理地转发。 +它是在任何特定消费者的控制之下，无论消费者是否由于本地考虑而选择接受或拒绝该大小的事件。 + +通常，CloudEvents 发布者应该通过避免将大型数据项嵌入到事件而使用事件有效链接到此类数据项， +来保持事件紧凑。 +从访问控制的角度来看，这种方法对更广泛的事件分布式化有帮助， +因为通过解析链接访问与事件相关的细节能实现差异化访问控制和选择性披露， +而不是将敏感详细数据直接嵌入到事件中。 + +# 隐私与安全 + +互操作性是本规范背后的主要驱动力， +实现此目标需要一些信息明确可用，这可能导致信息的泄漏。 + +考虑以下事项以防止信息意外泄漏，尤其是在利用第三方平台和通信网络时： + +- 上下文属性 + + 敏感信息不应在上下文属性中携带。 + + CloudEvent 生产者、消费者和中间人可以自查并记录下上下文属性。 + +- 数据 + + 特定的[事件数据](#事件数据) 应该被加密以限制对受信任方的可见性。 + 用于这种加密的机制是生产者和消费者之间的协议，不在本规范的讨论范围内。 + +- 协议绑定 + 应该采用协议级别的安全性机制来确保 CloudEvents 完成可信和安全的交换。 + +# 示例 + +以下示例展示了一个序列化为 JSON 的 CloudEvent： + +```JSON +{ + "specversion" : "1.0", + "type" : "com.github.pull.create", + "source" : "https://github.com/cloudevents/spec/pull", + "subject" : "123", + "id" : "A234-1234-1234", + "time" : "2018-04-05T17:31:00Z", + "comexampleextension1" : "value", + "comexampleothervalue" : 5, + "datacontenttype" : "text/xml", + "data" : "" +} +``` From 660ab95abf0ae1316197b7a275e9059184b49d18 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:29:15 +0800 Subject: [PATCH 21/60] Update spec.md --- spec.md | 863 +++++++++++++++++++++++++++++++------------------------- 1 file changed, 472 insertions(+), 391 deletions(-) diff --git a/spec.md b/spec.md index 7c9c1a8cd..5d3899541 100644 --- a/spec.md +++ b/spec.md @@ -1,466 +1,547 @@ -# CloudEvents 核心规范- 1.0 版本 +# CloudEvents - Version 1.0 -Declaration： This manual aims to provide a fast and brief introduction of CloudEvents -in Chinese for people who are new to CloudEvents. -Most of the content is translated from the original English version. -It is strongly recommended to read the English version if you find anything lost in translation. +## Abstract -## 摘要 +CloudEvents is a vendor-neutral specification for defining the format of event +data. -CloudEvents 是一个用于定义事件格式的供应商中立规范。 +## Table of Contents -## 目录 +- [Overview](#overview) +- [Notations and Terminology](#notations-and-terminology) +- [Context Attributes](#context-attributes) +- [Event Data](#event-data) +- [Size Limits](#size-limits) +- [Privacy & Security](#privacy-and-security) +- [Example](#example) -- [概览](#概览) -- [符号和术语](#符号和术语) -- [上下文属性](#上下文属性) -- [事件数据](#事件数据) -- [大小限制](#大小限制) -- [隐私与安全](#隐私与安全) -- [示例](#示例) +## Overview -## 概览 +Events are everywhere. However, event producers tend to describe events +differently. -事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 +The lack of a common way of describing events means developers are constantly +re-learning how to consume events. This also limits the potential for libraries, +tooling and infrastructure to aid the delivery of event data across +environments, like SDKs, event routers or tracing systems. The portability and +productivity that can be achieved from event data is hindered overall. -对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。 -它同样限制了那些用来帮助事件数据完成 跨环境传输的库(如SDKs)， -工具(如事件路由器)和基础设施(如事件追踪系统)的发展。 -总体来看，这种匮乏严重阻碍了事件数据的可移植性和生产力。 +CloudEvents is a specification for describing event data in common formats to +provide interoperability across services, platforms and systems. -CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 +Event Formats specify how to serialize a CloudEvent with certain encoding +formats. Compliant CloudEvents implementations that support those encodings MUST +adhere to the encoding rules specified in the respective event format. All +implementations MUST support the [JSON format](json-format.md). -事件格式指定如何使用某些编码格式序列化一个 CloudEvent。 -支持那些编码且兼容 CloudEvents 的实现必须遵守相应事件格式中指定的编码规则。 -所有实现都必须支持 [JSON 格式](json-format.md)。 +For more information on the history, development and design rationale behind the +specification, see the [CloudEvents Primer](primer.md) document. -有关规范背后的历史、开发和设计原理等更多信息， -请参阅 CloudEvents [入门文档](primer.md)。 +## Notations and Terminology -## 符号和术语 +### Notational Conventions -### 符号约定 +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). -本文档中的关键词 -"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 需要按照 -[RFC 2119](https://tools.ietf.org/html/rfc2119) 中的描述来理解。 +For clarity, when a feature is marked as "OPTIONAL" this means that it is +OPTIONAL for both the [Producer](#producer) and [Consumer](#consumer) of a +message to support that feature. In other words, a producer can choose to +include that feature in a message if it wants, and a consumer can choose to +support that feature if it wants. A consumer that does not support that feature +will then silently ignore that part of the message. The producer needs to be +prepared for the situation where a consumer ignores that feature. An +[Intermediary](#intermediary) SHOULD forward OPTIONAL attributes. -为清楚起见， -当一个功能被标记为“OPTIONAL”时，这意味着消息的 -[生产者](#生产者)和[消费者](#消费者) 都可以自行选择是否支持该功能。 -换句话说，生产者可以在需要时在消息中包含该功能，消费者也可以在需要时选择支持该功能。 -不支持该功能的消费者将默默地忽略该部分消息。 -生产者需要做好消费者并没有启用该功能的准备。 -[中间人](#中间人) 应当转发OPTIONAL属性。 +### Terminology -### 术语 +This specification defines the following terms: -本规范定义了下列术语 +#### Occurrence -#### 发生 +An "occurrence" is the capture of a statement of fact during the operation of a +software system. This might occur because of a signal raised by the system or a +signal being observed by the system, because of a state change, because of a +timer elapsing, or any other noteworthy activity. For example, a device might go +into an alert state because the battery is low, or a virtual machine is about to +perform a scheduled reboot. -“发生”是指在软件系统运行期间对事实状态的捕获。 -这可能是由于系统发出了信号或系统观察到信号、状态更改、计时器超时 -或任何其他值得注意的活动而发生的。 -例如，设备可能会因为电池电量低或虚拟机即将执行计划的重启而进入警报状态。 +#### Event -#### 事件 +An "event" is a data record expressing an occurrence and its context. Events are +routed from an event producer (the source) to interested event consumers. The +routing can be performed based on information contained in the event, but an +event will not identify a specific routing destination. Events will contain two +types of information: the [Event Data](#event-data) representing the Occurrence +and [Context](#context) metadata providing contextual information about the +Occurrence. A single occurrence MAY result in more than one event. -“事件”是表示一条"发生"及其上下文的数据记录。 -事件从事件生产者（源）路由到对它感兴趣的事件消费者。 -事件中包含的信息帮助完成路由操作，但事件不会标识特定的路由目的地。 -事件将包含两种类型的信息：表示"发生"的 [事件数据](#事件数据) -和提供有关事件的环境信息的[上下文](#上下文) 元数据。 -一次"发生"可能导致多个事件的产生。 +#### Producer -#### 生产者 +The "producer" is a specific instance, process or device that creates the data +structure describing the CloudEvent. -“生产者”是一种特定的实例、进程或设备，它能够创建用来描述CloudEvent的数据结构。 +#### Source -#### 源 +The "source" is the context in which the occurrence happened. In a distributed +system it might consist of multiple [Producers](#producer). If a source is not +aware of CloudEvents, an external producer creates the CloudEvent on behalf of +the source. -"源"是事件发生的上下文环境。在分布式系统中，它可能由多个生产者组成。 -如果一个源无法查看到CloudEvents，那么一定有有外部的生产者在代替源来生产CloudEvent。 +#### Consumer -#### 消费者 +A "consumer" receives the event and acts upon it. It uses the context and data +to execute some logic, which might lead to the occurrence of new events. -一个“消费者”会接收事件并根据事件采取一定的行为。 -它使用上下文环境和事件数据来执行一些逻辑，这可能会导致新事件的发生。 +#### Intermediary -#### 中间人 +An "intermediary" receives a message containing an event for the purpose of +forwarding it to the next receiver, which might be another intermediary or a +[Consumer](#consumer). A typical task for an intermediary is to route the event +to receivers based on the information in the [Context](#context). -一个“中间人”会接收包含事件的消息， -并将其转发给下一个接收者，但该接收者可能是另一个中间人或事件[消费者](#消费者)。 -中间人的典型任务就是根据[上下文](#上下文)环境中的信息将事件路由到接收者。 +#### Context + +Context metadata will be encapsulated in the +[Context Attributes](#context-attributes). Tools and application code can use +this information to identify the relationship of Events to aspects of the system +or to other Events. + +#### Data + +Domain-specific information about the occurrence (i.e. the payload). This might +include information about the occurrence, details about the data that was +changed, or more. See the [Event Data](#event-data) section for more +information. -#### 上下文 +#### Event Format + +An Event Format specifies how to serialize a CloudEvent as a sequence of bytes. +Stand-alone event formats, such as the [JSON format](json-format.md), specify +serialization independent of any protocol or storage medium. Protocol Bindings +MAY define formats that are dependent on the protocol. + +#### Message + +Events are transported from a source to a destination via messages. + +A "structured-mode message" is one where the event is fully encoded using +a stand-alone event format and stored in the message body. + +A "binary-mode message" is one where the event data is stored in the message +body, and event attributes are stored as part of message meta-data. + +#### Protocol + +Messages can be delivered through various industry standard protocol (e.g. HTTP, +AMQP, MQTT, SMTP), open-source protocols (e.g. Kafka, NATS), or platform/vendor +specific protocols (AWS Kinesis, Azure Event Grid). + +#### Protocol Binding + +A protocol binding describes how events are sent and received over a given +protocol, in particular how events are mapped to messages in that protocol. + +## Context Attributes + +Every CloudEvent conforming to this specification MUST include context +attributes designated as REQUIRED, MAY include one or more OPTIONAL context +attributes and MAY include one or more extension attributes. + +These attributes, while descriptive of the event, are designed such that they +can be serialized independent of the event data. This allows for them to be +inspected at the destination without having to deserialize the event data. -上下文环境元数据被封装在[上下文-属性](#上下文-属性)中。 -工具和应用程序代码可以使用此信息来识别事件与系统方面或事件与其他事件的关系。 - -#### 数据 - -关于事件的特定域信息（即有效负载）。这可能包括有关事件的信息、有关已更改数据的详细信息等。 -有关更多信息，请参阅[事件数据](#事件数据)部分。 - -#### 事件格式 - -一个事件格式会指定如何将 CloudEvent 序列化为字节序列。 -独立事件格式（例如 [JSON 格式](json-format.md)）指定独立于任何协议或存储介质的序列化。 -协议绑定可以定义依赖于协议的格式。 - -#### 消息 - -事件通过消息从源传输到目标。 - -“结构化模式消息”是一种使用独立事件格式对事件进行完全编码并存储在消息体中的消息。 - -“二进制模式消息”会将事件数据存储在消息体中，并将事件属性作为消息元数据的一部分存储下来。 - -#### 协议 - -消息可以通过各种行业标准协议 -（例如 HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或平台/供应商 -专有协议（AWS Kinesis、Azure 事件网格）传输。 - -#### 协议绑定 - -协议绑定描述了如何通过给定协议发送和接收事件，特别是如何将事件映射到该协议的消息中去。 - -## 上下文属性 - -每个符合本规范的 CloudEvent 必须包括指定为 REQUIRED 的上下文属性， -可以包括一个或多个OPTIONAL上下文属性， -并且可以包括一个或多个扩展属性。 - -这些属性虽然描述了事件，但被设计为可以独立于事件数据进行序列化。 -这允许在不反序列化事件数据的情况下，在目的检查这些上下文属性。 - -### 属性命名约定 - -CloudEvents 规范定义了到各种协议和编码的映射，随附的 CloudEvents SDK 面向各种运行时和编程语言。 -其中一些将元数据元素区分大小写，而另一些则不区分， -并且单个 CloudEvent 可能通过涉及到协议、编码和运行时混合的多个跃点进行路由。 -因此，本规范限制了所有属性的可用字符集，以防止区分大小写问题或与通用语言中标识符的合法字符集冲突问题。 - -CloudEvents 属性名称必须由来自 ASCII 字符集的小写字母（“a”到“z”）或数字（“0”到“9”）组成。 -属性名称应该是描述性的和简洁的，并且长度不应超过 20 个字符。 - -### 类型系统 - -以下抽象数据类型可用于属性。 -这些类型中的每一种都可以由不同的事件格式和协议元数据字段以不同的方式表示。 -本规范为所有实现必须支持的每种类型定义了规范的字符串编码。 - -- `Boolean` - “true”或“false”的布尔值。 - - 字符串编码：区分大小写的`true` 或 `false`值。 -- `Integer` -范围在 -2,147,483,648 到 +2,147,483,647 （包含）之间的整数。 - 这是有符号 32 位二进制补码编码的范围。 - 事件格式不必使用此编码，但它们必须使用在此范围内的`Integer` 值。 - - 字符串编码: 符合 - [RFC 7159, 第 6 节](https://tools.ietf.org/html/rfc7159#section-6) - JSON 数字的整数部分 -- `String` - 允许的 Unicode 字符序列。 不允许使用以下字符： - - 范围 U+0000-U+001F 和 U+007F-U+009F（包含首尾）中的“控制字符”， - 因为大多数没有商定的含义，还有一些，例如 U+000A（换行符）， 在如 HTTP 头部之类的上下文中不可用。 - -[被 Unicode 标识为非字符的](http://www.unicode.org/faq/private_use.html#noncharacters) - 代码点。 - - 被 Unicode 标识为代理项的代码点, 范围 U+D800-U+DBFF 和 U+DC00-U+DFFF（包含首尾） - , 除非被合理的用作代理对. 因此（在 JSON 符号中） - “\uDEAD”是无效的，因为它是一个未配对的代理，而“\uD800\uDEAD”是合法的。 -- `Binary` - 字节序列. - - 字符串编码: 基于 - [RFC4648](https://tools.ietf.org/html/rfc4648) 的Base64 编码。 -- `URI` - 绝对统一资源标识符。 - - 字符串编码: - [RFC 3986 第 4.3 节](https://tools.ietf.org/html/rfc3986#section-4.3) - 中定义的 `Absolute URI` 。 -- `URI-reference` - 统一资源标识符引用。 - - 字符串编码: - [RFC 3986 第 4.1 节](https://tools.ietf.org/html/rfc3986#section-4.1) - 中定义的`URI-reference` 。 -- `Timestamp` - 使用公历的日期和时间表达式。 - - 字符串编码: [RFC 3339](https://tools.ietf.org/html/rfc3339) 。 - -所有上下文属性值必须是上面列出的类型之一。 -属性值可以表示为原生类型或规范字符串。 - -当强类型编程语言表示 CloudEvent 或任何扩展时， -必须能够在规范字符串编码与对应抽象类型的运行时/编程语言类型之间进行转换。 - -例如，在给定的实现中，`time` 属性可能由编程语言的本地时间类型表示， -但它必须是可设置提供 RFC3339 字符串的， -并且当映射到 HTTP 消息头时，它必须可转换为 RFC3339 字符串。 - -CloudEvents 协议绑定或事件格式实现同样必须能够 -在规范字符串编码与协议元数据字段中的对应数据类型之间进行转换。 - -`Timestamp` 类型的属性值确实可能以字符串形式路由通过多个跃点， -并且仅在生产者和最终消费者处实现为本地运行时/语言类型。 -`Timestamp` 类型也可以作为本机协议类型路由， -并且可以在生产者和消费者端映射到/从各自的语言/运行时类型，但永远不会转为字符串格式。 - -序列化机制的选择将决定上下文属性和事件数据将如何序列化。 -例如，在 JSON 序列化的情况下，上下文属性和事件数据可能都出现在同一个 JSON 对象中。 - -### 必要属性 - -下列属性必须自所有的 CloudEvents 中展示： +### Attribute Naming Convention + +The CloudEvents specifications define mappings to various protocols and +encodings, and the accompanying CloudEvents SDK targets various runtimes and +languages. Some of these treat metadata elements as case-sensitive while others +do not, and a single CloudEvent might be routed via multiple hops that involve a +mix of protocols, encodings, and runtimes. Therefore, this specification limits +the available character set of all attributes such that case-sensitivity issues +or clashes with the permissible character set for identifiers in common +languages are prevented. + +CloudEvents attribute names MUST consist of lower-case letters ('a' to 'z') or +digits ('0' to '9') from the ASCII character set. Attribute names SHOULD be +descriptive and terse and SHOULD NOT exceed 20 characters in length. + +### Type System + +The following abstract data types are available for use in attributes. Each of +these types MAY be represented differently by different event formats and in +protocol metadata fields. This specification defines a canonical +string-encoding for each type that MUST be supported by all implementations. + +- `Boolean` - a boolean value of "true" or "false". + - String encoding: a case-sensitive value of `true` or `false`. +- `Integer` - A whole number in the range -2,147,483,648 to +2,147,483,647 + inclusive. This is the range of a signed, 32-bit, twos-complement encoding. + Event formats do not have to use this encoding, but they MUST only use + `Integer` values in this range. + - String encoding: Integer portion of the JSON Number per + [RFC 7159, Section 6](https://tools.ietf.org/html/rfc7159#section-6) +- `String` - Sequence of allowable Unicode characters. The following characters + are disallowed: + - the "control characters" in the ranges U+0000-U+001F and U+007F-U+009F (both + ranges inclusive), since most have no agreed-on meaning, and some, such as + U+000A (newline), are not usable in contexts such as HTTP headers. + - code points + [identified as noncharacters by Unicode](http://www.unicode.org/faq/private_use.html#noncharacters). + - code points identifying Surrogates, U+D800-U+DBFF and U+DC00-U+DFFF, both + ranges inclusive, unless used properly in pairs. Thus (in JSON notation) + "\uDEAD" is invalid because it is an unpaired surrogate, while + "\uD800\uDEAD" would be legal. +- `Binary` - Sequence of bytes. + - String encoding: Base64 encoding per + [RFC4648](https://tools.ietf.org/html/rfc4648). +- `URI` - Absolute uniform resource identifier. + - String encoding: `Absolute URI` as defined in + [RFC 3986 Section 4.3](https://tools.ietf.org/html/rfc3986#section-4.3). +- `URI-reference` - Uniform resource identifier reference. + - String encoding: `URI-reference` as defined in + [RFC 3986 Section 4.1](https://tools.ietf.org/html/rfc3986#section-4.1). +- `Timestamp` - Date and time expression using the Gregorian Calendar. + - String encoding: [RFC 3339](https://tools.ietf.org/html/rfc3339). + +All context attribute values MUST be of one of the types listed above. +Attribute values MAY be presented as native types or canonical strings. + +A strongly-typed programming model that represents a CloudEvent or any extension +MUST be able to convert from and to the canonical string-encoding to the +runtime/language native type that best corresponds to the abstract type. + +For example, the `time` attribute might be represented by the language's native +_datetime_ type in a given implementation, but it MUST be settable providing an +RFC3339 string, and it MUST be convertible to an RFC3339 string when mapped to a +header of an HTTP message. + +A CloudEvents protocol binding or event format implementation MUST likewise be +able to convert from and to the canonical string-encoding to the corresponding +data type in the encoding or in protocol metadata fields. + +An attribute value of type `Timestamp` might indeed be routed as a string +through multiple hops and only materialize as a native runtime/language type at +the producer and ultimate consumer. The `Timestamp` might also be routed as a +native protocol type and might be mapped to/from the respective +language/runtime types at the producer and consumer ends, and never materialize +as a string. + +The choice of serialization mechanism will determine how the context attributes +and the event data will be serialized. For example, in the case of a JSON +serialization, the context attributes and the event data might both appear +within the same JSON object. + +### REQUIRED Attributes + +The following attributes are REQUIRED to be present in all CloudEvents: #### id -- 类型: `String` -- 描述: 标识一个事件。 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 - 如果重复的事件被重新发送（例如由于网络错误），它可能具有相同的 `id`。 - Consumers MAY assume that - 消费者可以假设具有相同`source` 和 `id`的事件是重复的。 -- 示例: - - 一个由生产者维护的事件计数器 - - 一个 UUID -- 约束条件: - - 必要的 - - 必须是非空字符串 - - 在生产者的范围内必须是唯一的 +- Type: `String` +- Description: Identifies the event. Producers MUST ensure that `source` + `id` + is unique for each distinct event. If a duplicate event is re-sent (e.g. due + to a network error) it MAY have the same `id`. Consumers MAY assume that + Events with identical `source` and `id` are duplicates. +- Examples: + - An event counter maintained by the producer + - A UUID +- Constraints: + - REQUIRED + - MUST be a non-empty string + - MUST be unique within the scope of the producer #### source -- 类型: `URI-reference` -- 描述: 标识事件发生的上下文背景。 这通常包括诸如事件源类型、发布事件的组织 - 或产生事件的过程等信息。URI 中编码的数据背后的确切语法和语义由事件生产者定义。 - - 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 - - 应用程序可以为每个不同的生产者分配一个唯一的`source`， - 这使得生成唯一 ID 变得容易，因为没有其他生产者将拥有相同的来源。 - 应用程序可以使用 UUIDs、URNs、DNS权威机构或特定于应用程序的方案来创建唯一的`source` 标识符。 - - 一个来源可以包括多个生产者。 - 在这种情况下，生产者必须协作以确保每个不同事件的 `source` + `id`都是唯一的。 - -- 约束条件: - - 必要的 - - 必须是非空 URI-reference - - 推荐使用 绝对 URI -- 示例 - - 具有 DNS 权限的 Internet 范围唯一 URI： +- Type: `URI-reference` +- Description: Identifies the context in which an event happened. Often this + will include information such as the type of the event source, the + organization publishing the event or the process that produced the event. The + exact syntax and semantics behind the data encoded in the URI is defined by + the event producer. + + Producers MUST ensure that `source` + `id` is unique for each distinct event. + + An application MAY assign a unique `source` to each distinct producer, which + makes it easy to produce unique IDs since no other producer will have the same + source. The application MAY use UUIDs, URNs, DNS authorities or an + application-specific scheme to create unique `source` identifiers. + + A source MAY include more than one producer. In that case the producers MUST + collaborate to ensure that `source` + `id` is unique for each distinct event. + +- Constraints: + - REQUIRED + - MUST be a non-empty URI-reference + - An absolute URI is RECOMMENDED +- Examples + - Internet-wide unique URI with a DNS authority. - https://github.com/cloudevents - mailto:cncf-wg-serverless@lists.cncf.io - - 具有 UUID 的通用唯一 URN： + - Universally-unique URN with a UUID: - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 - - 应用程序专有的标识符 + - Application-specific identifiers - /cloudevents/spec/pull/123 - /sensors/tn-1234567/alerts - 1-555-123-4567 #### specversion -- 类型: `String` -- 描述: 事件使用的 CloudEvents 规范的版本。 - 这让解释上下文环境更容易。 - 当引用这个版本的规范时，兼容的事件生产者必须使用 `1.0` 的值。 -- 约束条件: - - 必要的 - - 必须是非空字符串 +- Type: `String` +- Description: The version of the CloudEvents specification which the event + uses. This enables the interpretation of the context. Compliant event + producers MUST use a value of `1.0` when referring to this version of the + specification. +- Constraints: + - REQUIRED + - MUST be a non-empty string #### type -- 类型: `String` -- 描述: 该属性包含一个值，描述与原始事件相关的事件类型。 - 该属性通常用于路由、可观察性、策略实施等。其格式是生产者定义的，可能包括诸如 `type`版本之类的信息 - -从 - [入门文档-属性版本控制](primer.md#属性版本控制) 中获得更多信息 - -- 约束条件: - - 必要的 - - 必须是非空字符串 - - 应该以反向 DNS 名称作为前缀。该前缀域表明了定义此事件类型语义的组织。 -- 示例 +- Type: `String` +- Description: This attribute contains a value describing the type of event + related to the originating occurrence. Often this attribute is used for + routing, observability, policy enforcement, etc. The format of this is + producer defined and might include information such as the version of the + `type` - see + [Versioning of Attributes in the Primer](primer.md#versioning-of-attributes) + for more information. +- Constraints: + - REQUIRED + - MUST be a non-empty string + - SHOULD be prefixed with a reverse-DNS name. The prefixed domain dictates the + organization which defines the semantics of this event type. +- Examples - com.github.pull.create - com.example.object.delete.v2 -### 可选属性 +### OPTIONAL Attributes -下列属性在 CloudEvents 中是可选的. 在 -[符号约定](#notational-conventions) 中查看更多 OPTIONAL 定义的信息。 +The following attributes are OPTIONAL to appear in CloudEvents. See the +[Notational Conventions](#notational-conventions) section for more information +on the definition of OPTIONAL. #### datacontenttype -- 类型: `String` [RFC 2046](https://tools.ietf.org/html/rfc2046) -- 描述: `data`值的内容类型。 此属性使`data`能够承载任何类型的内容， - 因此格式和编码可能与所选事件格式的不同。 - 例如，使用 [JSON envelope](./json-format.md#3-envelope) - 格式呈现的事件可能在数据中携带 XML 的payload，这个属性可以用来通知消费者 - 设置"application/xml"。 - 关于`data`内容如何提供不同的`datacontenttype`的值的规则在事件格式规范中定义。 - 例如，JSON 事件格式定义了 [3.1 节](./json-format.md#31-handling-of-data)中的关系。 - 对于某些二进制模式协议绑定， - 此字段直接能映射到相应协议的内容类型的元数据属性上。 - 二进制模式和内容类型元数据映射的规范规则可以在各自的协议中找到。 - - 在某些事件格式中，可以省略 `datacontenttype` 属性。 - 例如，如果 JSON 格式的事件没有 `datacontenttype` 属性， - 则表示该`data`是符合“application/json”媒体类型的 JSON 值。 - 换句话说：一个没有 `datacontenttype` 的 JSON 格式的事件完全等同于 - 一个带有 `datacontenttype="application/json"`的事件。 - - 当将没有 `datacontenttype` 属性的事件消息转换为不同的格式或协议绑定时， - 目标 `datacontenttype` 应该显式设置为事件源的隐含或默认的 `datacontenttype`。 - -- 约束条件: - - 可选的 - - 若有则必须遵守 - [RFC 2046](https://tools.ietf.org/html/rfc2046) 制定的格式 -- 媒体类型示例 +- Type: `String` per [RFC 2046](https://tools.ietf.org/html/rfc2046) +- Description: Content type of `data` value. This attribute enables `data` to + carry any type of content, whereby format and encoding might differ from that + of the chosen event format. For example, an event rendered using the + [JSON envelope](./json-format.md#3-envelope) format might carry an XML payload + in `data`, and the consumer is informed by this attribute being set to + "application/xml". The rules for how `data` content is rendered for different + `datacontenttype` values are defined in the event format specifications; for + example, the JSON event format defines the relationship in + [section 3.1](./json-format.md#31-handling-of-data). + + For some binary mode protocol bindings, this field is directly mapped to the + respective protocol's content-type metadata property. Normative rules for the + binary mode and the content-type metadata mapping can be found in the + respective protocol + + In some event formats the `datacontenttype` attribute MAY be omitted. For + example, if a JSON format event has no `datacontenttype` attribute, then it is + implied that the `data` is a JSON value conforming to the "application/json" + media type. In other words: a JSON-format event with no `datacontenttype` is + exactly equivalent to one with `datacontenttype="application/json"`. + + When translating an event message with no `datacontenttype` attribute to a + different format or protocol binding, the target `datacontenttype` SHOULD be + set explicitly to the implied `datacontenttype` of the source. + +- Constraints: + - OPTIONAL + - If present, MUST adhere to the format specified in + [RFC 2046](https://tools.ietf.org/html/rfc2046) +- For Media Type examples see [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml) #### dataschema -- 类型: `URI` -- 描述: 标识 `data` 遵守的规范。 对模式的不兼容的更改应该由不同的 URI 体现。 在 - [入门文档-属性版本控制](primer.md#属性版本控制) - 中查看更多信息。 -- 约束条件: - - 可选的 - - 若有必须是非空的 URI +- Type: `URI` +- Description: Identifies the schema that `data` adheres to. Incompatible + changes to the schema SHOULD be reflected by a different URI. See + [Versioning of Attributes in the Primer](primer.md#versioning-of-attributes) + for more information. +- Constraints: + - OPTIONAL + - If present, MUST be a non-empty URI #### subject -- 类型: `String` -- 描述: 这个属性描述了事件生产者 (由`source`标识) 上下文环境中的主题信息。 - 在发布-订阅场景中，订阅者通常会订阅`source`发出的事件， - 但如果`source` 的上下文环境具有内部子结构， - 则单独的`source`标识符可能不足以作为任何指定事件的限定符。 - - 在上下文元数据中识别事件的主题（与仅在数据负载中相反） - 对于中间件无法解释`data` 内容的通用订阅过滤场景特别有用。 - 在上面的示例中，订阅者可能只对名称以“.jpg”或“.jpeg”结尾的blob感兴趣， - 此时`subject` 属性允许为该事件子集构建简单有效的字符串后缀过滤器。 - -- 约束条件: - - 可选的 - - 若有必须是非空字符串 -- 示例: - - 订阅者可能对在blob在blob存储容器中创建的时候感兴趣并订阅。 - 在这个场景下，事件`source`标示出订阅的范围（存储容器），`type` 标识出 - blob 创建" 这个事件，`id` 唯一标识出事件示例，以区分已创建同名blob的事件， - 而新创建的blob的名字可以放在`subject`属性中： +- Type: `String` +- Description: This describes the subject of the event in the context of the + event producer (identified by `source`). In publish-subscribe scenarios, a + subscriber will typically subscribe to events emitted by a `source`, but the + `source` identifier alone might not be sufficient as a qualifier for any + specific event if the `source` context has internal sub-structure. + + Identifying the subject of the event in context metadata (opposed to only in + the `data` payload) is particularly helpful in generic subscription filtering + scenarios where middleware is unable to interpret the `data` content. In the + above example, the subscriber might only be interested in blobs with names + ending with '.jpg' or '.jpeg' and the `subject` attribute allows for + constructing a simple and efficient string-suffix filter for that subset of + events. + +- Constraints: + - OPTIONAL + - If present, MUST be a non-empty string +- Example: + - A subscriber might register interest for when new blobs are created inside a + blob-storage container. In this case, the event `source` identifies the + subscription scope (storage container), the `type` identifies the "blob + created" event, and the `id` uniquely identifies the event instance to + distinguish separate occurrences of a same-named blob having been created; + the name of the newly created blob is carried in `subject`: - `source`: https://example.com/storage/tenant/container - `subject`: mynewfile.jpg #### time -- 类型: `Timestamp` -- 描述: 事件发生的时间戳。 - 如果无法确定发生的时间，则 CloudEvents 生产者可以将此属性设置为其他时间（例如当前时间）。 - 但是在这方面，同一`source`的所有生产者必须保持一致。 - 换句话说，要么它们都使用发生的实际时间，要么它们都使用相同的算法来确定所使用的值。 - -- 约束条件: - - 可选的 - - 若有则必须遵守 +- Type: `Timestamp` +- Description: Timestamp of when the occurrence happened. If the time of the + occurrence cannot be determined then this attribute MAY be set to some other + time (such as the current time) by the CloudEvents producer, however all + producers for the same `source` MUST be consistent in this respect. In other + words, either they all use the actual time of the occurrence or they all use + the same algorithm to determine the value used. +- Constraints: + - OPTIONAL + - If present, MUST adhere to the format specified in [RFC 3339](https://tools.ietf.org/html/rfc3339) -### 扩展上下文属性 - -CloudEvent 可以包含任意数量的具有不同名称的附加上下文属性，被称为"扩展属性"。 -扩展属性必须遵循相同的[命名约定](#属性命名约定)并使用与标准属性相同的 -[类型系统](#类型系统)。 -扩展属性在本规范中没有定义好的含义， -它们允许外部系统将元数据附加到事件，就像 HTTP 自定义头部一样。 - -扩展属性总是如标准属性一样，根据绑定规则进行序列化。 -然而，该规范不阻止扩展将事件属性值复制到消息的其他部分， -以便与也其它处理消息的非 CloudEvents 系统进行交互。 -如果复制的值与云事件序列化值不同，执行此操作的扩展规范应该指定接收者如何解释消息。 - -#### 定义扩展 - -在 -[CloudEvent-属性扩展](primer.md#CloudEvent-属性扩展) -查阅有关扩展使用和定义等相关信息。 - -扩展的定义应该完全定义属性的方方面面——例如 它的名称、类型、语义含义和可能的值。 -新的扩展定义应该使用一个足够描述性的名称来减少与其他扩展的名称冲突的机会。 -特别是，扩展作者应该检查[扩展文件](documented-extensions.md)中 -已知的扩展集——不仅是可能的名称冲突，还有相同目的冲突的扩展。 - -许多协议为发送者提供了包含额外元数据的能力，例如作为 HTTP 头部。 -虽然没有强制要求 CloudEvents 接受者处理和传递它们， -但建议接受者通过某种机制进行处理，以明确它们是非 CloudEvents 的元数据。 - -下面是一个示例，说明了 CloudEvents 对附加属性的需求。 -在许多物联网和企业用例中，事件可用于跨多种类型事件执行操作的serverless应用程序中。 -为了支持这样的用例，事件生产者需要向“上下文属性”添加额外的身份属性， -事件消费者可以使用这些属性将这个事件与其他事件相关联。 -如果此类身份属性恰好是事件“数据”的一部分， -则事件生产者还会将身份属性添加到“上下文属性”中， -以便事件消费者可以轻松访问此信息，而无需解码和检查事件数据。 -此类身份属性还可用于帮助中间网关确定如何路由事件。 - -## 事件数据 - -正如[数据](#数据)所定义的那样，CloudEvents 可以包括有关事件的特定域的信息。 -这些信息将被封装在`data`中。 - -- 描述: 事件负载。 本规范对该信息的类型不作任何限制。 - 它被编码为一种媒体格式，这种格式由`datacontenttype` 属性(如 application/json)指定， - 并在存在这些相应属性时遵循`dataschema`格式。 - It is encoded into a media format - -- 约束条件: - - 可选的 - -# 大小限制 - -在很多情况下，CloudEvents 将通过一个或多个通用中间人进行转发， -每个中间人都可能对转发事件的大小施加限制。 -CloudEvents 也可能直接被路由到消费者，如嵌入式设备， -这些设备是受存储或内存限制的，对单个大型事件表现不佳。 - -事件的“大小”是它的线路大小，包括在线路上为事件传输的每一位： -协议帧元数据、事件元数据和事件数据，基于所选的事件格式和所选的协议绑定。 - -如果应用程序配置需要跨不同协议路由事件或重新编码事件， -应用程序能使用的效率最低的协议和编码，都修腰符合这些大小限制： - -- 中间人转发的事件大小必须为 64 KB 或更小。 -- 消费者应该能接受大小至少为 64 KB 的事件。 - -为了方便，上述规则将允许生产者安全地发布最大 64KB 的事件。 -这里的安全意味着生产者期望事件被所有中间人接受并合理地转发。 -它是在任何特定消费者的控制之下，无论消费者是否由于本地考虑而选择接受或拒绝该大小的事件。 - -通常，CloudEvents 发布者应该通过避免将大型数据项嵌入到事件而使用事件有效链接到此类数据项， -来保持事件紧凑。 -从访问控制的角度来看，这种方法对更广泛的事件分布式化有帮助， -因为通过解析链接访问与事件相关的细节能实现差异化访问控制和选择性披露， -而不是将敏感详细数据直接嵌入到事件中。 - -# 隐私与安全 - -互操作性是本规范背后的主要驱动力， -实现此目标需要一些信息明确可用，这可能导致信息的泄漏。 - -考虑以下事项以防止信息意外泄漏，尤其是在利用第三方平台和通信网络时： - -- 上下文属性 - - 敏感信息不应在上下文属性中携带。 - - CloudEvent 生产者、消费者和中间人可以自查并记录下上下文属性。 - -- 数据 - - 特定的[事件数据](#事件数据) 应该被加密以限制对受信任方的可见性。 - 用于这种加密的机制是生产者和消费者之间的协议，不在本规范的讨论范围内。 - -- 协议绑定 - 应该采用协议级别的安全性机制来确保 CloudEvents 完成可信和安全的交换。 +### Extension Context Attributes + +A CloudEvent MAY include any number of additional context attributes with +distinct names, known as "extension attributes". Extension attributes MUST +follow the same [naming convention](#attribute-naming-convention) and use the +same [type system](#type-system) as standard attributes. Extension attributes +have no defined meaning in this specification, they allow external systems to +attach metadata to an event, much like HTTP custom headers. + +Extension attributes are always serialized according to binding rules like +standard attributes. However this specification does not prevent an extension +from copying event attribute values to other parts of a message, in order to +interact with non-CloudEvents systems that also process the message. Extension +specifications that do this SHOULD specify how receivers are to interpret +messages if the copied values differ from the cloud-event serialized values. + +#### Defining Extensions + +See +[CloudEvent Attributes Extensions](primer.md#cloudevent-attribute-extensions) +for additional information concerning the use and definition of extensions. + +The definition of an extension SHOULD fully define all aspects of the +attribute - e.g. its name, type, semantic meaning and possible values. New +extension definitions SHOULD use a name that is descriptive enough to reduce the +chances of name collisions with other extensions. In particular, extension +authors SHOULD check the [documented extensions](documented-extensions.md) +document for the set of known extensions - not just for possible name conflicts +but for extensions that might be of interest. + +Many protocols support the ability for senders to include additional metadata, +for example as HTTP headers. While a CloudEvents receiver is not mandated to +process and pass them along, it is RECOMMENDED that they do so via some +mechanism that makes it clear they are non-CloudEvents metadata. + +Here is an example that illustrates the need for additional attributes. In many +IoT and enterprise use cases, an event could be used in a serverless application +that performs actions across multiple types of events. To support such use +cases, the event producer will need to add additional identity attributes to the +"context attributes" which the event consumers can use to correlate this event +with the other events. If such identity attributes happen to be part of the +event "data", the event producer would also add the identity attributes to the +"context attributes" so that event consumers can easily access this information +without needing to decode and examine the event data. Such identity attributes +can also be used to help intermediate gateways determine how to route the +events. + +## Event Data + +As defined by the term [Data](#data), CloudEvents MAY include domain-specific +information about the occurrence. When present, this information will be +encapsulated within `data`. + +- Description: The event payload. This specification does not place any + restriction on the type of this information. It is encoded into a media format + which is specified by the `datacontenttype` attribute (e.g. application/json), + and adheres to the `dataschema` format when those respective attributes are + present. + +- Constraints: + - OPTIONAL + +# Size Limits + +In many scenarios, CloudEvents will be forwarded through one or more generic +intermediaries, each of which might impose limits on the size of forwarded +events. CloudEvents might also be routed to consumers, like embedded devices, +that are storage or memory-constrained and therefore would struggle with large +singular events. + +The "size" of an event is its wire-size and includes every bit that is +transmitted on the wire for the event: protocol frame-metadata, event metadata, +and event data, based on the chosen event format and the chosen protocol +binding. + +If an application configuration requires for events to be routed across +different protocols or for events to be re-encoded, the least efficient +protocol and encoding used by the application SHOULD be considered for +compliance with these size constraints: + +- Intermediaries MUST forward events of a size of 64 KByte or less. +- Consumers SHOULD accept events of a size of at least 64 KByte. + +In effect, these rules will allow producers to publish events up to 64KB in size +safely. Safely here means that it is generally reasonable to expect the event to +be accepted and retransmitted by all intermediaries. It is in any particular +consumer's control, whether it wants to accept or reject events of that size due +to local considerations. + +Generally, CloudEvents publishers SHOULD keep events compact by avoiding +embedding large data items into event payloads and rather use the event payload +to link to such data items. From an access control perspective, this approach +also allows for a broader distribution of events, because accessing +event-related details through resolving links allows for differentiated access +control and selective disclosure, rather than having sensitive details embedded +in the event directly. + +# Privacy and Security + +Interoperability is the primary driver behind this specification, enabling such +behavior requires some information to be made available _in the clear_ resulting +in the potential for information leakage. + +Consider the following to prevent inadvertent leakage especially when leveraging +3rd party platforms and communication networks: + +- Context Attributes + + Sensitive information SHOULD NOT be carried or represented in context + attributes. + + CloudEvent producers, consumers, and intermediaries MAY introspect and log + context attributes. + +- Data -# 示例 + Domain specific [event data](#event-data) SHOULD be encrypted to restrict + visibility to trusted parties. The mechanism employed for such encryption is + an agreement between producers and consumers and thus outside the scope of + this specification. + +- Protocol Bindings + + Protocol level security SHOULD be employed to ensure the trusted and secure + exchange of CloudEvents. + +# Example -以下示例展示了一个序列化为 JSON 的 CloudEvent： +The following example shows a CloudEvent serialized as JSON: ```JSON { From 21905a26512309cf3f8f8c6f4d2a84df3bf1dc83 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:31:08 +0800 Subject: [PATCH 22/60] Update README_CN.md --- README_CN.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README_CN.md b/README_CN.md index 64a4ee4f7..8c6145b7c 100644 --- a/README_CN.md +++ b/README_CN.md @@ -45,9 +45,9 @@ CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvent | Primer | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/primer.md) | [master](https://github.com/cloudevents/spec/blob/master/primer.md) | | Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | -对于初次接触CloudEvents的同学，可以通过阅读[入门文档](primer.md)增加对CloudEvents规范的目标和设计理念 +对于初次接触CloudEvents的同学，可以通过阅读[入门文档](primer_CN.md)增加对CloudEvents规范的目标和设计理念 的总体理解， -希望在最短时间内使用CloudEvents 规范的同学，可以直接阅读[核心规范](spec.md)。 +希望在最短时间内使用CloudEvents 规范的同学，可以直接阅读[核心规范](spec_CN.md)。 由于并非所有事件生产者都默认生产符合CloudEvents规范的事件，因此可以用[CloudEvents适配器](https://github.com/cloudevents/spec/blob/master/adapters.md) 来将现有的事件与CloudEvents做适配。 @@ -74,8 +74,8 @@ CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvent ## 步骤 -CloudEvents项目 [旨在](primer.md#设计目标)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 -的[标准](spec.md)。 +CloudEvents项目 [旨在](primer_CN.md#设计目标)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 +的[标准](spec_CN.md)。 为了完成这个目标，这个项目必须描述： From d221c0a3ddfb320c62e6bae816efa2538a492ddb Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:34:39 +0800 Subject: [PATCH 23/60] Update primer_CN.md --- primer_CN.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/primer_CN.md b/primer_CN.md index a5382f71f..5b5b77bc6 100644 --- a/primer_CN.md +++ b/primer_CN.md @@ -40,7 +40,7 @@ Serverless相关技术并为CNCF推荐相关领域的未来发展计划的。工 ## CloudEvents-概念 -一个[事件](spec.md#事件)包含了[事件发生](spec.md#发生)的上下文和相关数据。 +一个[事件](spec_CN.md#事件)包含了[事件发生](spec_CN.md#发生)的上下文和相关数据。 事件的相关数据可以用来唯一标识一件事件的发生。 事件代表了已发生的事实，因此它并不包含任何目的地相关信息，但消息能够传达事件内容，从而将事件数据 @@ -98,7 +98,7 @@ CloudEvents的核心规范中定义了一组称之为属性的元数据， 为了提升系统间的互操作性，是否以及如何实现批处理将由协议自己决定。 相关详细信息可以在协议绑定或协议规范中找到。 成批的CloudEvents并没有语义，也没有排序。 -[中间人](spec.md#中间人)可以添加或删除批处理以及将事件分配给不同的批处理。 +[中间人](spec_CN.md#中间人)可以添加或删除批处理以及将事件分配给不同的批处理。 ### 非目标 @@ -135,9 +135,9 @@ CloudEvents 应该增加互操作性并解耦事件的生产者和消费者。 CloudEvents 规范集定义了四种有助于形成分层架构模型的不同类型的协议元素。 基本规范定义了一个抽象信息模型，该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 -1. [基本规范](spec.md) 定义了一个抽象信息模型， +1. [基本规范](spec_CN.md) 定义了一个抽象信息模型， 该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 -2. [扩展属性](./spec.md#扩展上下文属性) +2. [扩展属性](./spec_CN.md#扩展上下文属性) 添加了特定于用例且可能重叠的扩展属性集和相关规则，如支持不同的追踪标准的规则。 3. 事件格式编码,如 [JSON](json-format.md), 定义了基本规范的信息模型与所选扩展的编码方式， 以将其映射到应用程序协议的头部和负载元素。 @@ -428,9 +428,9 @@ CloudEvents的努力不应成为认可或推广项目或产品专有协议的工 事件是否可通过中间件消费取决于生产者的选择。 - 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec.md#生产者)的角色， - 当它根据事件采取行动时可以扮演[消费者](spec.md#消费者)的角色， - 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec.md#中间人)的角色。 + 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec_CN.md#生产者)的角色， + 当它根据事件采取行动时可以扮演[消费者](spec_CN.md#消费者)的角色， + 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec_CN.md#中间人)的角色。 4. 框架和其他抽象使与事件平台基础设施间的交互更简单， 并且通常为多个事件平台基础设施提供公共 API 区域。 From 73308d3d9cca5a15f32bb1365023bb5e6c661b5f Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:37:00 +0800 Subject: [PATCH 24/60] Update spec_CN.md --- spec_CN.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec_CN.md b/spec_CN.md index 7c9c1a8cd..e27e009d3 100644 --- a/spec_CN.md +++ b/spec_CN.md @@ -35,7 +35,7 @@ CloudEvents是一个以通用格式来描述事件数据的标准。它提供了 所有实现都必须支持 [JSON 格式](json-format.md)。 有关规范背后的历史、开发和设计原理等更多信息， -请参阅 CloudEvents [入门文档](primer.md)。 +请参阅 CloudEvents [入门文档](primer_CN.md)。 ## 符号和术语 @@ -269,7 +269,7 @@ CloudEvents 协议绑定或事件格式实现同样必须能够 - 描述: 该属性包含一个值，描述与原始事件相关的事件类型。 该属性通常用于路由、可观察性、策略实施等。其格式是生产者定义的，可能包括诸如 `type`版本之类的信息 -从 - [入门文档-属性版本控制](primer.md#属性版本控制) 中获得更多信息 + [入门文档-属性版本控制](primer_CN.md#属性版本控制) 中获得更多信息 - 约束条件: - 必要的 @@ -318,7 +318,7 @@ CloudEvents 协议绑定或事件格式实现同样必须能够 - 类型: `URI` - 描述: 标识 `data` 遵守的规范。 对模式的不兼容的更改应该由不同的 URI 体现。 在 - [入门文档-属性版本控制](primer.md#属性版本控制) + [入门文档-属性版本控制](primer_CN.md#属性版本控制) 中查看更多信息。 - 约束条件: - 可选的 @@ -377,7 +377,7 @@ CloudEvent 可以包含任意数量的具有不同名称的附加上下文属性 #### 定义扩展 在 -[CloudEvent-属性扩展](primer.md#CloudEvent-属性扩展) +[CloudEvent-属性扩展](primer_CN.md#CloudEvent-属性扩展) 查阅有关扩展使用和定义等相关信息。 扩展的定义应该完全定义属性的方方面面——例如 它的名称、类型、语义含义和可能的值。 From 10fba3ea6b1a28c201a985d010cd854006da906d Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:52:55 +0800 Subject: [PATCH 25/60] Create README_CN.md --- Chinese Manual/README_CN.md | 132 ++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 Chinese Manual/README_CN.md diff --git a/Chinese Manual/README_CN.md b/Chinese Manual/README_CN.md new file mode 100644 index 000000000..8c6145b7c --- /dev/null +++ b/Chinese Manual/README_CN.md @@ -0,0 +1,132 @@ +# CloudEvents 中文手册 + +![CloudEvents logo](https://github.com/cncf/artwork/blob/master/projects/cloudevents/horizontal/color/cloudevents-horizontal-color.png) + +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. + +事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 + +对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。它同样限制了那些用来帮助事件数据完成 +跨环境传输的库(如SDKs)，工具(如事件路由器)和基础设施(如事件追踪系统)的发展。总体来看，这种匮乏严重阻碍了事件数据的 +可移植性和生产力。 + +CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 + +CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvents被[云原生计算基金会](https://cncf.io) (CNCF)持有， +在[2018/05/15](https://docs.google.com/presentation/d/1KNSv70fyTfSqUerCnccV7eEC_ynhLsm9A_kjnlmU_t0/edit#slide=id.g37acf52904_1_41) +被选为云原生沙箱级项目。 + +## CloudEvents 文件 + +现有文件如下: + +| | 最新版本 | 工作草稿 | +| :---------------------------- | :----------------------------------------------------------------------------: | :---------------------------------------------------------------------------------: | +| **核心标准:** | +| CloudEvents | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/spec.md) | [master](https://github.com/cloudevents/spec/blob/master/spec.md) | +| | +| **可选标准:** | +| AMQP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/amqp-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-protocol-binding.md) | +| AVRO Event Format | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/avro-format.md) | [master](https://github.com/cloudevents/spec/blob/master/avro-format.md) | +| HTTP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/http-protocol-binding.md) | +| JSON Event Format | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/json-format.md) | [master](https://github.com/cloudevents/spec/blob/master/json-format.md) | +| Kafka Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/kafka-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/kafka-protocol-binding.md) | +| MQTT Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/mqtt-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/mqtt-protocol-binding.md) | +| NATS Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/nats-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/nats-protocol-binding.md) | +| Web hook | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md) | [master](https://github.com/cloudevents/spec/blob/master/http-webhook.md) | +| | +| **附加文件:** | +| CloudEvents Adapters | - | [master](https://github.com/cloudevents/spec/blob/master/adapters.md) | +| CloudEvents SDK Requirements | - | [master](https://github.com/cloudevents/spec/blob/master/SDK.md) | +| Documented Extensions | - | [master](https://github.com/cloudevents/spec/blob/master/documented-extensions.md) | +| Primer | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/primer.md) | [master](https://github.com/cloudevents/spec/blob/master/primer.md) | +| Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | + +对于初次接触CloudEvents的同学，可以通过阅读[入门文档](primer_CN.md)增加对CloudEvents规范的目标和设计理念 +的总体理解， +希望在最短时间内使用CloudEvents 规范的同学，可以直接阅读[核心规范](spec_CN.md)。 + +由于并非所有事件生产者都默认生产符合CloudEvents规范的事件，因此可以用[CloudEvents适配器](https://github.com/cloudevents/spec/blob/master/adapters.md) +来将现有的事件与CloudEvents做适配。 + +## SDKs + +除了上述文档，我们还提供了[SDK 提议](SDK.md)以及一些编程语言的SDK： + +- [CSharp](https://github.com/cloudevents/sdk-csharp) +- [Go](https://github.com/cloudevents/sdk-go) +- [Java](https://github.com/cloudevents/sdk-java) +- [Javascript](https://github.com/cloudevents/sdk-javascript) +- [Python](https://github.com/cloudevents/sdk-python) + +## 社区 + +在社区里，你可以了解到更多致力于搭建一个动态、云原生的生态系统的成员和组织。 +他们不断尝试提升现有系统和CloudEvents间的互操作性和兼容性。 + +- [贡献者](community/contributors.md): + 是指那些帮助我们制定规范或是积极活跃在CloudEvents规范相关工作的成员和组织。 +- 即将推出: [demos & open source](community/README.md) -- + 如果你希望向我们分享关于你对CloudEvents的使用，请通过提交PR让我们看到。 + +## 步骤 + +CloudEvents项目 [旨在](primer_CN.md#设计目标)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 +的[标准](spec_CN.md)。 + +为了完成这个目标，这个项目必须描述： + +- 一系列能够提升互操作性的用来描述事件的属性 +- 一个或多个通用架构，这些架构必须是当下活跃的或是正在计划被完成的 +- 事件是如何在一种或多种协议下从生产者传输到消费者的 +- 识别并解决任何能提升互操作性的问题 +## 联系方式 + +邮件联系方式如下: + +- 发送EMail至: [cncf-cloudevents](mailto:cncf-cloudevents@lists.cncf.io) +- 订阅地址: https://lists.cncf.io/g/cncf-cloudevents +- 存档地址: https://lists.cncf.io/g/cncf-cloudevents/topics + +## 会议时间 + +会议日期请查看 [CNCF 公开活动日历](https://www.cncf.io/community/calendar/). +CloudEvents规范由 +[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 开发完成。 +这个工作组每周四的上午9点(美国-太平洋时间)通过Zoom开展视频会议。 +通过 PC, Mac, Linux, iOS or Android来参加活动: https://zoom.us/my/cncfserverlesswg + +或者通过 iPhone one-tap : + + US: +16465588656,,3361029682# or +16699006833,,3361029682# + +或者电话接入: + + Dial: + US: +1 646 558 8656 (US Toll) or +1 669 900 6833 (US Toll) + or +1 855 880 1246 (Toll Free) or +1 877 369 0926 (Toll Free) + +会议 ID: 336 102 9682 + +国际号码接入: +https://zoom.us/zoomconference?m=QpOqQYfTzY_Gbj9_8jPtsplp1pnVUKDr + +世界时区转化器: +http://www.thetimezoneconverter.com/?t=9:00%20am&tz=San%20Francisco& + +## 会议记录 + +历史会议记录在 +[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) +查看。 + +历史会议录像在 +[这里](https://www.youtube.com/playlist?list=PLj6h78yzYM2Ph7YoBIgsZNW_RGJvNlFOt) +查看。 + +工作组会定期举办与主流会议一致的线下会议。查看[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) +了解更多未来计划。 + From 40f281d73e6d3cebf352e6d62bf1650fd59a95e5 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:53:32 +0800 Subject: [PATCH 26/60] Delete README_CN.md --- README_CN.md | 132 --------------------------------------------------- 1 file changed, 132 deletions(-) delete mode 100644 README_CN.md diff --git a/README_CN.md b/README_CN.md deleted file mode 100644 index 8c6145b7c..000000000 --- a/README_CN.md +++ /dev/null @@ -1,132 +0,0 @@ -# CloudEvents 中文手册 - -![CloudEvents logo](https://github.com/cncf/artwork/blob/master/projects/cloudevents/horizontal/color/cloudevents-horizontal-color.png) - -Declaration： This manual aims to provide a fast and brief introduction of CloudEvents -in Chinese for people who are new to CloudEvents. -Most of the content is translated from the original English version. -It is strongly recommended to read the English version if you find anything lost in translation. - -事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 - -对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。它同样限制了那些用来帮助事件数据完成 -跨环境传输的库(如SDKs)，工具(如事件路由器)和基础设施(如事件追踪系统)的发展。总体来看，这种匮乏严重阻碍了事件数据的 -可移植性和生产力。 - -CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 - -CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvents被[云原生计算基金会](https://cncf.io) (CNCF)持有， -在[2018/05/15](https://docs.google.com/presentation/d/1KNSv70fyTfSqUerCnccV7eEC_ynhLsm9A_kjnlmU_t0/edit#slide=id.g37acf52904_1_41) -被选为云原生沙箱级项目。 - -## CloudEvents 文件 - -现有文件如下: - -| | 最新版本 | 工作草稿 | -| :---------------------------- | :----------------------------------------------------------------------------: | :---------------------------------------------------------------------------------: | -| **核心标准:** | -| CloudEvents | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/spec.md) | [master](https://github.com/cloudevents/spec/blob/master/spec.md) | -| | -| **可选标准:** | -| AMQP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/amqp-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-protocol-binding.md) | -| AVRO Event Format | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/avro-format.md) | [master](https://github.com/cloudevents/spec/blob/master/avro-format.md) | -| HTTP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/http-protocol-binding.md) | -| JSON Event Format | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/json-format.md) | [master](https://github.com/cloudevents/spec/blob/master/json-format.md) | -| Kafka Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/kafka-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/kafka-protocol-binding.md) | -| MQTT Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/mqtt-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/mqtt-protocol-binding.md) | -| NATS Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/nats-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/nats-protocol-binding.md) | -| Web hook | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md) | [master](https://github.com/cloudevents/spec/blob/master/http-webhook.md) | -| | -| **附加文件:** | -| CloudEvents Adapters | - | [master](https://github.com/cloudevents/spec/blob/master/adapters.md) | -| CloudEvents SDK Requirements | - | [master](https://github.com/cloudevents/spec/blob/master/SDK.md) | -| Documented Extensions | - | [master](https://github.com/cloudevents/spec/blob/master/documented-extensions.md) | -| Primer | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/primer.md) | [master](https://github.com/cloudevents/spec/blob/master/primer.md) | -| Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | - -对于初次接触CloudEvents的同学，可以通过阅读[入门文档](primer_CN.md)增加对CloudEvents规范的目标和设计理念 -的总体理解， -希望在最短时间内使用CloudEvents 规范的同学，可以直接阅读[核心规范](spec_CN.md)。 - -由于并非所有事件生产者都默认生产符合CloudEvents规范的事件，因此可以用[CloudEvents适配器](https://github.com/cloudevents/spec/blob/master/adapters.md) -来将现有的事件与CloudEvents做适配。 - -## SDKs - -除了上述文档，我们还提供了[SDK 提议](SDK.md)以及一些编程语言的SDK： - -- [CSharp](https://github.com/cloudevents/sdk-csharp) -- [Go](https://github.com/cloudevents/sdk-go) -- [Java](https://github.com/cloudevents/sdk-java) -- [Javascript](https://github.com/cloudevents/sdk-javascript) -- [Python](https://github.com/cloudevents/sdk-python) - -## 社区 - -在社区里，你可以了解到更多致力于搭建一个动态、云原生的生态系统的成员和组织。 -他们不断尝试提升现有系统和CloudEvents间的互操作性和兼容性。 - -- [贡献者](community/contributors.md): - 是指那些帮助我们制定规范或是积极活跃在CloudEvents规范相关工作的成员和组织。 -- 即将推出: [demos & open source](community/README.md) -- - 如果你希望向我们分享关于你对CloudEvents的使用，请通过提交PR让我们看到。 - -## 步骤 - -CloudEvents项目 [旨在](primer_CN.md#设计目标)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 -的[标准](spec_CN.md)。 - -为了完成这个目标，这个项目必须描述： - -- 一系列能够提升互操作性的用来描述事件的属性 -- 一个或多个通用架构，这些架构必须是当下活跃的或是正在计划被完成的 -- 事件是如何在一种或多种协议下从生产者传输到消费者的 -- 识别并解决任何能提升互操作性的问题 -## 联系方式 - -邮件联系方式如下: - -- 发送EMail至: [cncf-cloudevents](mailto:cncf-cloudevents@lists.cncf.io) -- 订阅地址: https://lists.cncf.io/g/cncf-cloudevents -- 存档地址: https://lists.cncf.io/g/cncf-cloudevents/topics - -## 会议时间 - -会议日期请查看 [CNCF 公开活动日历](https://www.cncf.io/community/calendar/). -CloudEvents规范由 -[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 开发完成。 -这个工作组每周四的上午9点(美国-太平洋时间)通过Zoom开展视频会议。 -通过 PC, Mac, Linux, iOS or Android来参加活动: https://zoom.us/my/cncfserverlesswg - -或者通过 iPhone one-tap : - - US: +16465588656,,3361029682# or +16699006833,,3361029682# - -或者电话接入: - - Dial: - US: +1 646 558 8656 (US Toll) or +1 669 900 6833 (US Toll) - or +1 855 880 1246 (Toll Free) or +1 877 369 0926 (Toll Free) - -会议 ID: 336 102 9682 - -国际号码接入: -https://zoom.us/zoomconference?m=QpOqQYfTzY_Gbj9_8jPtsplp1pnVUKDr - -世界时区转化器: -http://www.thetimezoneconverter.com/?t=9:00%20am&tz=San%20Francisco& - -## 会议记录 - -历史会议记录在 -[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) -查看。 - -历史会议录像在 -[这里](https://www.youtube.com/playlist?list=PLj6h78yzYM2Ph7YoBIgsZNW_RGJvNlFOt) -查看。 - -工作组会定期举办与主流会议一致的线下会议。查看[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) -了解更多未来计划。 - From fc3bb0f69fea5aadf1a165d7376650685061903e Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:53:54 +0800 Subject: [PATCH 27/60] Create primer_CN.md --- Chinese Manual/primer_CN.md | 704 ++++++++++++++++++++++++++++++++++++ 1 file changed, 704 insertions(+) create mode 100644 Chinese Manual/primer_CN.md diff --git a/Chinese Manual/primer_CN.md b/Chinese Manual/primer_CN.md new file mode 100644 index 000000000..5b5b77bc6 --- /dev/null +++ b/Chinese Manual/primer_CN.md @@ -0,0 +1,704 @@ +# CloudEvents 入门文档 - 1.0 版本 + +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. + +## 摘要 + +这份非技术规范文档用来为你提供关于CloudEvents规范的总体概览。它补充了CloudEvents规范的相关背景 +以及在制定 本规范时的历史和设计理念。这样，CloudEvents的核心规范就只需要关注Events规范的技术细节， +而不用过多地关心背景相关内容。 + +## 目录 + +- [历史](#历史) +- [CloudEvents 概念](#CloudEvents-概念) +- [设计目标](#设计目标) +- [架构](#架构) +- [属性版本控制](#属性版本控制) +- [CloudEvent 属性](#CloudEvent-属性) +- [CloudEvent 属性扩展](#CloudEvent-属性扩展) +- [生产 CloudEvents](#生产CloudEvents) +- [合格的协议与编码](#合格的协议与编码) +- [专有的协议和编码](#专有的协议与编码) +- [现有技术](#现有技术) +- [角色](#角色) +- [价值主张](#价值主张) +- [现有的数据格式](#现有的数据格式) + +## 历史 + +[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 是由 CNCF的 +[技术监管委员会](https://github.com/cncf/toc) 成立，用于研究 +Serverless相关技术并为CNCF推荐相关领域的未来发展计划的。工作组其中一项建议就是研究创建一种通用事件格式， +用于提升不同云厂商间函数的可移植性和事件流处理的互操作性。就此，CloudEvents应运而生。 + +尽管CloudEvents起初是作为Serverless工作组的项目进行的，但随着CloudEvents规范完成它v0.1版本的里程碑， +技术监管委员会批准了CloudEvents作为一个新的独立的CNCF沙箱级项目。 + +## CloudEvents-概念 + +一个[事件](spec_CN.md#事件)包含了[事件发生](spec_CN.md#发生)的上下文和相关数据。 +事件的相关数据可以用来唯一标识一件事件的发生。 + +事件代表了已发生的事实，因此它并不包含任何目的地相关信息，但消息能够传达事件内容，从而将事件数据 +从源头传输到指定的目的地。 + +### 事件使用 + +事件通常在服务器端代码中使用来连接不同的系统，其中一个系统中的状态变化会导致代码在另一个系统中执行。 +比如，一个事件源，可能会在收到某个外部信号(如HTTP或RPC)或观察到状态变化(如IoT传感器数据变化或不活跃) +时，生产一个事件。 + +为了更好地解释一个系统如何使用CloudEvents，下图展示了一个从事件源生产的事件是如何触发一个行为的。 + +![alt text](source-event-action.png "A box representing the source with +arrow pointing to a box representing the action. The arrow is annotated with +'e' for event and 'protocol'.") + +事件源生产了一条封装了基于某种协议的事件数据的消息。 +当载有事件的消息到达目的地时，会触发一个使用了事件数据的行为函数。 + +一个事件源是那些允许暂存和测试实例的源类型的特定实例。 +某个特定源类型的开源软件可能由多个公司或提供商部署。 + +事件可以通过各种行业标准协议（如HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或 +平台/供应商专有协议（AWS Kinesis、Azure Event Grid）传输。 + +一个操作函数能够处理那些定义了行为或影响的事件，这些行为和效果由来自特定源的特定事件触发而来。 +虽然超出了规范的范围，但生成事件的目的通常是让其他系统能够轻松地对它们无法控制的源中的更改做出反应。 +源和操作通常由不同的开发人员构建。 +通常，源是托管服务，而操作是serverless函数（如 AWS Lambda 或 Google Cloud Functions）中 +的自定义代码。 + +## 设计目标 + +CloudEvents 通常用于分布式系统，以允许服务在开发过程中松耦合，独立部署，方便之后连接以创建新的应用程序。 + +CloudEvents 规范的目标是定义允许服务生产或消费事件的事件系统的互操作性， +其中生产者和消费者可以独立开发和部署。 生产者可以在没有消费者监听时就生成事件， +消费者也可以表达对尚未生成的事件或事件类的兴趣。值得注意的是，这项工作产生的规范侧重于事件格式的互操作性 +以及它在通过各种协议（例如 HTTP）发送时的显示方式。我们不关注事件生产者或事件消费者的处理模型。 + +CloudEvents的核心规范中定义了一组称之为属性的元数据， +它们描述了在系统之间传输的事件以及这些元数据片段应如何显示在该消息中。 +这些元数据是，将请求路由到适当组件并帮助该组件正确处理事件所需的最小信息集。 +因此，某些事件本身的数据可能会作为 CloudEvent 属性集的一部分而被复制， +但这样做仅是为了能够正确传递和处理消息。那些不用于该目的的数据应放置在事件（数据）本身中。 + +此外，本规范中假设协议层所需的用来将消息传递到目标系统的元数据应完全由协议处理， +因此不包含在 CloudEvents 属性中。 有关更多详细信息，请参阅[非目标](#非目标)部分。 + +除了这些属性的定义之外，规范还描述了关于如何序列化 +不同格式（例如 JSON）和协议（例如 HTTP、AMQP、Kafka）的事件。 + +一些协议本身支持将多个事件批处理到单个 API 的调用中。 +为了提升系统间的互操作性，是否以及如何实现批处理将由协议自己决定。 +相关详细信息可以在协议绑定或协议规范中找到。 +成批的CloudEvents并没有语义，也没有排序。 +[中间人](spec_CN.md#中间人)可以添加或删除批处理以及将事件分配给不同的批处理。 + +### 非目标 + +以下内容不在本规范的范围之内： + +- 函数的构建和调用过程 +- 特定语言的运行时 APIs +- 选择单一身份认证或访问控制的系统 +- 包含协议级路由信息 +- 事件持久化过程 + +就连那些刚接触 CloudEvents 概念的人都会建议 +CloudEvents 规范不应包括协议级路由信息（例如，将事件发送到的目标的URL）。 +经过深思熟虑，工作组得出的结论是，CloudEvents规范中不需要路由信息： +因为任何现有的协议（例如 HTTP、MQTT、XMPP 或 Pub/Sub 总线）都已经定义了路由语义。 +例如，CloudEvents [HTTP 绑定](http-protocol-binding.md) 规定了头部和请求正文内容。 +CloudEvents 不需要在规范中包含目标 URL 即可与 HTTP 兼容；HTTP 规范已经在 +[请求行](https://tools.ietf.org/html/rfc2616#section-5.1) 中包含了所需的目标URL。 + +路由信息不仅是多余的，而且是有害的。 +CloudEvents 应该增加互操作性并解耦事件的生产者和消费者。 +禁止来自事件格式的路由信息允许将 CloudEvents 重新传送到新的行为，或通过包含多个通道的复杂中继传送。 +例如，如果 Webhook 地址不可用，则用于 Webhook 的 CloudEvent 应可传送到死信队列。 +死信队列应该能够将事件传送给原始事件发射者从未想象过的新的行为上。 + +在系统内和跨系统生产和消费的 CloudEvent能够触发产生价值的行为。 +因此，对于调试或复制的目的而言，存档和或重放事件可能很有价值。 +但是，持久化事件会删除传输期间可用的上下文信息，例如生产者的身份和权利、保真验证机制或机密性保护。 +此外，持久化会增加满足用户需求的复杂性和挑战。 +例如，出于加密或签名目的重复使用私钥会增加攻击者可用的信息，从而降低安全性。 +因此我们推测，可以定义有助于满足持久性要求的属性，但这些属性可能随着行业最佳实践和进步而不断发展。 + +## 架构 +CloudEvents 规范集定义了四种有助于形成分层架构模型的不同类型的协议元素。 +基本规范定义了一个抽象信息模型，该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 + +1. [基本规范](spec_CN.md) 定义了一个抽象信息模型， + 该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 +2. [扩展属性](./spec_CN.md#扩展上下文属性) + 添加了特定于用例且可能重叠的扩展属性集和相关规则，如支持不同的追踪标准的规则。 +3. 事件格式编码,如 [JSON](json-format.md), 定义了基本规范的信息模型与所选扩展的编码方式， + 以将其映射到应用程序协议的头部和负载元素。 +4. 协议绑定, 如. [HTTP协议绑定](http-protocol-binding.md), + 在HTTP to HTTP的情况下， + 定义了 CloudEvent 如何绑定到应用程序协议的传输层 。 + 协议绑定不限制传输层的使用方式，这意味着 HTTP绑定可用于任何 HTTP方法以及请求和响应消息。 + +为了确保更广泛的互操作性，CloudEvents规范集为使用专有应用协议的事件传输提供了特定约束。 +[HTTP Webhook](http-webhook.md)规范并非特定于 CloudEvents， +而是可用于将任何类型的单向事件和通知发布到符合标准的 HTTP 端点。 +但是，由于其他地方缺乏此类规范，因此 CloudEvents 需要对其进行定义。 + +### 协议错误处理 + +CloudEvents 规范在很大程度上并未规定与 CloudEvents 的创建或处理相关联的处理模型。 +因此，如果在处理 CloudEvent 过程中出现错误， +请使用正常的协议级错误处理机制进行处理。 + +## 属性版本控制 + +对于某些 CloudEvents 属性，由其值引用的实体或数据模型可能会随时间变化。 +例如，`dataschema`可能引用模式文档的一个特定版本。 +通常，这些属性值会通过将一些特定于版本的字符串作为其值的一部分来区分每个变体。 +例如，可能会加入版本号 (v1, v2) 或日期 (2018-01-01)来区分。 + +CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强制使用版本字符串。 +是否使用完全取决于每个事件生产者。 +但是，当使用特定版本的字符串时，每当其值发生变化时都应注意， +因为事件消费者可能依赖于现有值，因此更改可能被解释为“破坏性更改”。 +应该在生产者和消费者之间建立某种形式的通信，以确保事件消费者知道能使用哪些可能的值。 +通常，这也适用于所有 CloudEvents 属性。 + +## CloudEvent-属性 + +本节介绍了与CloudEvent 属性相关的其他背景和设计要点。 + +### id + +`id` 属性是一个在同一事件源下所有事件中用来标识事件唯一的值 +（其中每个事件源由其 CloudEvents `source`属性唯一标识）。 +虽然`id`使用的确切值是生产者定义的， +但必须要确保来自单个事件源的 CloudEvents 消费者不会有两个事件共享相同的 id 值。 +唯一的例外是如果支持事件的重播，在这些情况下，可以使用 id 来检测这一点。 + +由于一次事件的发生可能导致生成多个cloud event， +在所有这些事件都来自同一事件源的情况下， +生成的每个 CloudEvent 将具有唯一的 `id`。 +以创建数据库条目为例，这一事件的发生可能会生成一个类型为 create 的 CloudEvent +和一个类型为 write 的 CloudEvent。 +这两个 CloudEvents 各自都有一个唯一的 ID。 +如果需要在这两个 CloudEvent 之间建立某种关联以表明它们都与同一事件相关， +那么可以使用 CloudEvent 中的一些附加数据来实现该目的。 + +从这方面来看，虽然事件生产者对`id`的使用可能是某个随机字符串， +或者在其它上下文中具有某种语义的字符串， +但对于此 CloudEvent 属性而言，这些含义并不成立， +因此本规范不建议将 `id` 用于除了唯一性检查之外的其它目的。 + +## CloudEvent-属性扩展 + +为了实现规范的设计目标， +规范作者将尝试限制他们在 CloudEvents 中定义的元数据属性的数量。 +为此，该项目定义的属性将分为以下三类： + +- 必要属性 +- 可选属性 +- 扩展属性 + +正如类别名称所暗示的那样， +“必要”属性是工作组认为在任何情况下，对所有事件都至关重要的属性， +而“可选”属性将在大多数情况下使用。 这些情况下的两个属性都在本规范中定义了出来。 + +工作组考虑到某些属性不够常见而不能归入上述两个类别， +但此类属性的良好定义仍会使系统间的互操作性级别受益， +因此将这些属性放入了“扩展”类别并记录在[扩展文档](documented-extensions.md)中， +本规范定义了这些扩展属性在 CloudEvent 中的显示方式。 + +在确定提议的属性属于哪个类别时， +工作组使用现有的用例和用户故事来解释它们的基本原理和需求。 +相关信息将添加到本文档的[现有技术](#现有技术)部分。 + +CloudEvent 规范的扩展属性是需要包含的附加元数据，它们能确保正确的路由和正确处理CloudEvent。 +用于其它目的的附加元数据， +即那些与事件本身相但在 CloudEvent 的传输或处理中不需要的元数据， +应改为放置在事件 (`data`)的扩展点内。 + +扩展属性应保持最少，以确保 CloudEvent 可以正确序列化和传输。 +事件生产者应该考虑在向 CloudEvent 添加扩展时可能遇到的技术限制。 +例如，[HTTP Binary Mode](http-protocol-binding.md#31-binary-content-mode) +使用 HTTP 头来传输元数据； +大多数 HTTP 服务器会拒绝包含过多 HTTP 头部数据的请求，要求限制其低至 8kb。 +因此，扩展属性的大小和数量应保持最小。 + +如果扩展变得流行，那么规范作者可能会考虑将其作为核心属性移入规范。 +这意味着在正式将新属性添加到规范之前，扩展机制/过程可用作审查新属性的一种方式。 + +### JSON 扩展 + +如 [CloudEvents JSON 事件格式](json-format.md)中 +[属性](json-format.md#2-attributes)部分所述， +CloudEvent 扩展属性与已定义属性(必要属性、可选属性)在序列化时处于同一等级 - +也就是说，它们都是 JSON 对象的顶层属性。 +CloudEvent的作者花了很长时间考虑所有选项，并认为这是最好的选择。 +理由如下： + +由于CloudEvents规范遵循 [semver](https://semver.org/) ， +这意味着只要新属性是可选属性，它们可以在核心规范的未来版本定义，而无需更改当前主要版本。 +在这样的情况下，请考虑现有消费者将如何使用新的（未知的）顶级属性。 +虽然消费者可以随意忽略它，因为它是可选的， +但在大多数情况下，这些属性仍然希望向接收这些事件的应用程序公开。 +这可能导致这些应用程序在基础设施不支持的情况下，支持这些属性。 +这意味着未知的顶级属性（无论是谁定义的——规范的未来版本或事件生产者）可能不会被忽略。 +因此，虽然其它一些规范定义了放置扩展的特定属性（例如顶级`extensions`属性）， +但作者认为在传入事件中具有两个不同位置的未知属性可能会导致互操作性问题和开发人员的混淆。 + +扩展属性通常用于测试那些被规范正式采用之前的潜在属性。 +如果有一个`extensions`类型的属性，这个新属性已经被序列化， +那么如果该属性被核心规范采用，它将从`extensions`属性提升（从序列化的角度）为顶级属性。 +如果我们假设这个新属性是可选的，那么当它被核心规范采用时， +它只是一个小版本增量，所有现有的消费者仍然会继续工作。 +但是，消费者将不知道此属性将出现在何处 - 在扩展属性中还是作为顶级属性。 +这意味着他们可能需要同时查看两个地方。 +如果属性出现在两个地方但具有不同的值怎么办？ +生产者是否需要将它放在两个地方，因为他们可能同时有新、老消费者？ +虽然可以为如何解决出现的每个潜在问题而制定明确的规则， +但作者认为一个避免这些问题的更好的办法是在序列化中只有一个位置来放置未知的甚至是新的属性。 +作者还注意到 HTTP 规范现在遵循类似的模式，不再建议扩展 HTTP 头部以 X- 为前缀。 + +## 生产CloudEvents + +CloudEvents 规范有意避免将CloudEvents 的创建方式设计的过于死板。 +例如，它不假定原始事件源必须是该事件生产对应 CloudEvent 的同一实体。 +这允许多种实现方式。 +但是，对于规范的实现者来说，理解规范作者心中的期望还是有帮助的，因为这将有助于确保互操作性和一致性。 + +如上所述，生成初始事件的实体是否与创建相应 CloudEvent 的实体相同是由实现决定的。 +但是，当构建/填充 CloudEvents 属性的实体代表事件源进行操作时，这些属性的值是用来描述事件或事件源， +而不是计算 CloudEvent 属性值的实体的。 +换句话说，当事件源和 CloudEvents 生产者之间的分离对事件使用者没有实质性意义时， +规范定义的属性通常不会包含任何值来指示这种职责分离。 + +这并不是说 CloudEvents 生产者不能向 CloudEvent 添加一些额外的属性， +但这些属性超出了规范的互操作性定义属性的范围。 +这类似于 HTTP 代理通常如何最大限度地减少对传入消息的明确定义的 HTTP 头部的更改， +但它可能会添加一些额外的头部，其中包括一些特定代理的元数据。 + +还值得注意的是，原始事件源和 CloudEvents 生产者之间的这种分离可大可小。 +意思是，即使 CloudEvent 生产者不是原始事件源生态系统的一部分， +如果它代表事件源行事，并且它在事件流中的存在对事件消费者没有意义，那么上述指导仍然适用。 + +当实体同时充当 CloudEvents 的接收者和发送者以转发或转换传入事件时， +出站 CloudEvent 与入站 CloudEvent 匹配的程度将根据该实体的处理语义而有所不同。 +在它充当代理的情况下，它只是将 CloudEvents 转发给另一个事件消费者， +那么出站 CloudEvent 通常看起来与入站 CloudEvent 就规范定义的属性相同 +- 请参阅上一段有关添加其他属性的内容。 + +但是，如果此实体正在执行 CloudEvent 的某种类型的语义处理， +通常会导致`data`属性值发生更改， +则可能需要将其视为与原始事件源不同的“事件源”。 +因此，与事件生产者相关的 CloudEvents 属性（例如`source` and `id`） +将从传入的 CloudEvent 中更改。 + +## 合格的协议与编码 + +正如规范中所表达的，CloudEvents 工作的明确目标是 +“以通用方式描述事件数据”且 +“定义允许服务产生或消费事件的事件系统的互操作性，其中生产者和消费者可以被独立开发和部署”。 + +这种互操作性的基础是开放的数据格式和协议， +CloudEvents 旨在提供这种开放的数据格式，并将其数据格式映射到常用协议和常用编码上。 + +虽然每个软件或服务产品和项目都可以自己选择自己喜欢的通信形式， +但毫无疑问，这种产品或项目私有的专有协议无法进一步实现跨生产者和消费者的广泛互操作性的目标。 + +特别是在消息传递和事件处理领域，该行业在过去十年中开发出了强大且受到广泛支持的协议 +例如 HTTP 1.1 和 HTTP/2 以及 WebSockets 或 Web 上的事件，或者 MQTT 和 AMQP +用于面向连接的消息传递和遥测传输的协议。 + +一些广泛使用的协议已经成为事实上的标准，这些协议来自三个或更多公司的顶级财团打造的强大生态系统， +还有一些来自单个公司发布的强大项目生态系统，在任何一种情况下都与前面提到的标准栈的演变相一致。 + +CloudEvents的努力不应成为认可或推广项目或产品专有协议的工具， +因为这与CloudEvents 的原始目标背道而驰。 + +要使协议或编码符合核心 CloudEvents 事件格式或协议绑定的条件，它必须属于以下任一类别： + +- 该协议具有广泛认可的多供应商协议标准化机构（例如 W3C、IETF、OASIS、ISO）的正式标准地位 +- 该协议在其生态系统类别中具有“事实上的标准”地位， + 这意味着它被广泛使用，甚至被认为是给定应用程序的标准。 + 实际上，我们希望在供应商中立的开源组织（例如 Apache、Eclipse、CNCF、.NET 基金会）的保护伞下 + 看到至少一个开源实现， + 并且至少有十几个独立供应商在他们的产品中使用它的产品或服务。 + +除了正式状态之外，协议或编码是否符合核心 CloudEvents 事件格式或协议绑定的一个关键标准是， +该组织是否认为协议或编码出现后，该规范对与产品或项目无关的任何一方具有持续的实际利益。 +对此的基本要求是协议或编码的定义方式允许独立于产品或项目代码的替代实现。 + +欢迎将 CloudEvents 的所有其他协议和编码格式 +包含在指向相应项目自己的公共仓库，或站点中的 CloudEvents binding信息的列表中。 + +## 专有的协议与编码 + +为了鼓励更多人采用 CloudEvents，本仓库将自动收集专有协议和编码。 +本仓库的维护人员不负责创建、维护或通知专有规范的维护人员有关专有规范和CloudEvents规范间的偏差。 + +专有规范将托管在他们自己的仓库或文档站点中，并记录在[专有规范](proprietary-specs.md) +文件中。 专有规范应遵循与核心协议和编码相关的其他规范相同的格式。 + +专有规范将比核心规范受到更少的审查，并且随着 CloudEvents 规范的发展， +相应协议和编码的维护者有责任使规范与 CloudEvents 规范保持同步。 +如果专有规范过时太多，CloudEvents 可能会将指向该规范的链接标记为已弃用或将其删除。 + +如果为同一个协议创建了多个不兼容的规范，存储库维护者将不知道哪个规范是正确的，并列出所有规范的链接。 + +## 现有技术 + +本节介绍了工作组在 CloudEvent 规范开发过程中使用的一些输入材料。 + +### 角色 + +下面列举了可能涉及事件的产生、管理或消费的各种参与者和场景。 + +在这些中，事件生产者和事件消费者的角色是不同的。 +单个应用程序上下文背景始终可以同时承担多个角色，包括既是事件的生产者又是事件的消费者。 + +1. 应用程序生成供他人使用的事件， + 如为消费者提供有关终端用户活动、状态变化或环境观察的见解， + 或允许通过事件驱动的扩展来补充应用程序的功能。 + + 生产的事件通常与上下文或生产者选择的分类相关。 + 例如，房间中的温度传感器可能被安装位置、房间、楼层和建筑物等上下文限定。 + 运动结果可以按联赛和球队分类。 + + 生产者应用程序可以在任何地方运行，例如在服务器或设备上。 + + 生产的事件可能由生产者或中间人直接提供和发出； + 作为后者的示例，请考虑设备通过负载大小受限的网络（如 LoRaWAN 或 ModBus）传输的事件数据， + 并且符合此规范的事件将由网络网关代表生产者提供。 + + 例如，气象站每 5 分钟通过 LoRaWAN 传输一次 12 字节的专有事件payload用于指示天气状况。 + 然后使用 LoRaWAN 网关以 CloudEvents 格式将事件发布到 Internet 目标。 + LoRaWAN 网关是事件生产者，代表气象站发布事件，并将设置一定的元数据以反映事件的来源(气象站)。 + +2. 应用程序可能以以下目的： + 如显示、存档、分析、工作流处理、监控状态或提供业务解决方案及其基本构建模块的透明化 + 来消费事件。 + + 消费者应用程序可以在任何地方运行，例如在服务器或设备上。 + + 消费应用程序通常对以下内容感兴趣： + + - 区分事件，使得完全相同的事件不会被处理两次。 + - 识别和选择源上下文或生产者指定的分类。 + - 确定事件相对于原始上下文或相对于时钟的时间顺序。 + - 了解事件中携带的上下文相关的详细信息。 + - 关联来自多个事件生产者的事件实例并将它们发送到相同的消费者上下文。 + + 在某些情况下，消费应用程序可能对以下内容感兴趣： + + - 从原始上下文中获取有关事件主题的更多详细信息，例如获取有关需要特权访问授权的已更改对象的详细信息。 + 例如，出于隐私原因，HR 解决方案可能仅在事件中发布非常有限的信息， + 任何需要更多数据的事件消费者都必须在其自己的授权上下文背景下从 HR 系统获取与事件相关的详细信息 + - 在原始上下文中与事件的主题进行交互，例如在被告知该数据块刚刚创建后读取存储该数据块。 + + 消费者的兴趣激发了信息生产者应该包括事件的需求。 + +3. 中间件将事件从生产者路由到消费者，或转发到其他中间件。 + 产生事件的应用程序可能会将根据消费者需求产生的某些任务委托给中间件： + + - 管理同时对大量类别和上下文背景中的某个事件感兴趣的消费者。 + - 代表消费者在类或事件的原始上下文上处理过滤条件。 + - 转码，比如从 JSON 解码后在 MsgPack 中编码。 + - 更改事件结构的转换，例如从专有格式映射到 CloudEvents，同时保留事件的身份和语义完整性。 + - 即时“推送式”传输给感兴趣的消费者。 + - 存储最终传输的事件，用于由消费者发起的“拉”请求，或延迟后由中间件发起“推”请求。 + - 观察事件内容或事件流以进行监控或诊断。 + + 为了满足这些需求，中间件将对以下方面感兴趣： + + - 一种元数据鉴别器，可用于事件的分类或上下文化，以便消费者可以表达对一个或多个类或上下文的兴趣。 + 例如，消费者可能对文件存储帐户内的特定目录相关的所有事件感兴趣。 + - 一种元数据鉴别器，允许区分该类或上下文的特定事件的主题。例如，消费者可能希望过滤掉与以“.jpg”结尾的 + 新文件相关的所有事件（文件名是“新文件”事件的主题），以此表示它对感兴趣的文件存储账户下某个目录的 + 上下文环境。 + - 一个事件及其数据编码的指示器。 + - 一个事件及其数据的结构布局（模式）的指示器。 + + 事件是否可通过中间件消费取决于生产者的选择。 + + 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec_CN.md#生产者)的角色， + 当它根据事件采取行动时可以扮演[消费者](spec_CN.md#消费者)的角色， + 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec_CN.md#中间人)的角色。 + +4. 框架和其他抽象使与事件平台基础设施间的交互更简单， + 并且通常为多个事件平台基础设施提供公共 API 区域。 + + 框架通常用于将事件转换为对象图，并将事件分派给某些特定的处理逻辑或用户规则， + 这些用户逻辑或用户规则允许消费应用程序对原始上下文和特定主题中的特定类型的事件做出反应。 + + 框架最感兴趣的是跨抽象平台的语义元数据通用性，以便可以统一处理类似的活动。 + + 对于体育应用程序，使用该框架的开发人员可能对联盟中一支球队今天的比赛（主题） + 的所有事件感兴趣，但希望以不同于“换人”事件的方式处理“得分”事件。 + 为此，框架将需要一个合适的元数据鉴别器，使其不必了解事件细节。 + +### 价值主张 + +本节介绍了一些能够展示 CloudEvents 价值主张的用例。 + +#### 跨服务和平台规范化事件 + +主要事件发布者（例如 AWS、Microsoft、Google 等）都在各自的平台上以不同的格式发布事件。 +甚至在少数情况下，同一提供商的服务以不同格式（例如 AWS）发布事件。 +这迫使事件消费者实现自定义逻辑以跨平台读取或处理事件数据，有时甚至需要跨单个平台的多个服务处理。 + +CloudEvents 可以为那些跨平台和服务处理事件的使用者提供单一体验。 + +#### 促进跨服务和平台的集成 + +跨环境传输的事件数据越来越普遍。 +然而，如果没有描述事件的通用方式，跨环境的事件传递就会受到阻碍。 +CloudEvents之前没有单一的方法可以确定事件的来源和可能的去向。 +这对研究成功传输事件事件工具和消费者知道如何处理事件数据形成了巨大阻碍。 + +CloudEvents 提供有用的元数据，中间件和消费者可以依赖这些元数据来促进事件路由、日志记录、传输和接收。 + +#### 提高功能即服务的可移植性 + +功能即服务（也称为serverless计算）是 IT 中增长最快的趋势之一，它主要是由事件驱动的。 +然而，FaaS 的一个主要问题是供应商锁定。 +这种锁定部分是由函数 API 和供应商之间签名的差异引起的， +锁定同样也是由函数内接收的事件数据格式的差异引起的。 + +CloudEvents提供描述事件数据的通用方式提高了功能即服务的可移植性。 + +#### 改进事件驱动/serverless架构的开发和测试 + +缺乏通用事件格式使事件驱动和serverless架构的开发和测试变得复杂。 +没有简单的方法可以准确地为开发和测试目的模拟事件，并帮助在开发环境中模拟事件驱动的工作流。 + +CloudEvents 可以提供更好的开发工具来构建、测试和处理事件驱动和无服务器架构的端到端生命周期。 + +#### 事件数据发展 + +大多数平台和服务对其事件的数据模型进行不同的版本控制（如果他们这样做的话）。 +随着这些数据模型的发展，这会为发布和使用事件的数据模型带来不一致的体验。 + +CloudEvents 可以提供一种通用的方式来版本化和演化事件数据的发展。 +这将帮助事件发布者根据最佳实践安全地对其数据模型进行版本控制， +并且这有助于事件消费者随着事件数据的发展安全地使用它。 + +#### 规范化 Webhook + +Webhooks 是一种不使用通用格式的来发布事件的模式。 +Webhook 的使用者没有一致的方式来开发、测试、识别、验证和整体处理通过 Webhook 传输的事件数据。 + +CloudEvents 可以提供 Webhook 发布和消费事件的一致性。 + +#### 安全策略 + +出于安全和策略考虑，可能需要过滤、转换或阻止系统之间的事件传输。 +比如可能需要防止事件的进入或退出，如包含敏感信息的事件数据或想要禁止发送方和接收方之间的信息流。 + +通用事件格式将允许更容易地推理正在传输的数据，并提供更好的数据自查。 + +#### 事件追踪 + +从源发送的事件可能会出现在一系列附加事件序列之中， +这些附加事件序列从各种中间件设备（例如事件代理和网关）发出。 +CloudEvents 在事件中包含元数据以将这些事件关联为事件序列的一部分，以便进行事件跟踪和故障排除。 + +#### IoT + +物联网设备会发送和接收与其功能相关的事件。 +例如，连接的恒温器将发送有关当前温度的遥测数据， +并可以接收改变温度的事件。 +这些设备通常具有受限的操作环境（cpu、内存），需要明确定义的事件消息格式。 +在很多情况下，这些消息是二进制编码的，而不是文本的。 +无论是直接来自设备还是通过网关转换，CloudEvents 都可以更好地描述消息的来源和消息中包含的数据格式。 + +#### 事件关联 + +一个serverless应用或工作流可能与来自不同事件源或事件生产者的多个事件相关联。 +例如，盗窃检测应用程序/工作流可能涉及运动事件和门/窗打开事件。 +一个serverless平台可能接收每种类型事件的许多实例，例如 它可以接收来自不同房屋的运动事件和开窗事件。 + +serverless平台需要将一种类型的事件实例与其他类型的事件实例正确关联， +并将接收到的事件实例映射到正确的应用/工作流实例。 +CloudEvents 将为任何事件使用者（例如serverless平台）提供一种标准方式， +以在事件数据中定位事件关联信息/令牌并将接收到的事件实例映射到正确的应用/工作流实例。 + +### 现有的数据格式 + +与上一节一样，对当前现状的调查（和理解）对CloudEvents 小组来说非常重要。 +为此，下面列出了在实践中被广泛使用的当前事件格式的样本。 + +#### Microsoft - Event Grid + +``` +{ + "topic":"/subscriptions/{subscription-id}", + "subject":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/eventSubscriptions/LogicAppdd584bdf-8347-49c9-b9a9-d1f980783501", + "eventType":"Microsoft.Resources.ResourceWriteSuccess", + "eventTime":"2017-08-16T03:54:38.2696833Z", + "id":"25b3b0d0-d79b-44d5-9963-440d4e6a9bba", + "data": { + "authorization":"{azure_resource_manager_authorizations}", + "claims":"{azure_resource_manager_claims}", + "correlationId":"54ef1e39-6a82-44b3-abc1-bdeb6ce4d3c6", + "httpRequest":"", + "resourceProvider":"Microsoft.EventGrid", + "resourceUri":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/eventSubscriptions/LogicAppdd584bdf-8347-49c9-b9a9-d1f980783501", + "operationName":"Microsoft.EventGrid/eventSubscriptions/write", + "status":"Succeeded", + "subscriptionId":"{subscription-id}", + "tenantId":"72f988bf-86f1-41af-91ab-2d7cd011db47" + } +} +``` + +[Documentation](https://docs.microsoft.com/en-us/azure/event-grid/event-schema) + +#### Google - Cloud Functions (potential future) + +``` +{ + "data": { + "@type": "types.googleapis.com/google.pubsub.v1.PubsubMessage", + "attributes": { + "foo": "bar", + }, + "messageId": "12345", + "publishTime": "2017-06-05T12:00:00.000Z", + "data": "somebase64encodedmessage" + }, + "context": { + "eventId": "12345", + "timestamp": "2017-06-05T12:00:00.000Z", + "eventTypeId": "google.pubsub.topic.publish", + "resource": { + "name": "projects/myProject/topics/myTopic", + "service": "pubsub.googleapis.com" + } + } +} +``` + +#### AWS - CloudWatch Events + +AWS 上的很大一部分事件处理系统都在使用这种格式。 + +``` +{ + "version": "0", + "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718", + "detail-type": "EC2 Instance State-change Notification", + "source": "aws.ec2", + "account": "111122223333", + "time": "2017-12-22T18:43:48Z", + "region": "us-west-1", + "resources": [ + "arn:aws:ec2:us-west-1:123456789012:instance/i-1234567890abcdef0" + ], + "detail": { + "instance-id": "i-1234567890abcdef0", + "state": "terminated" + } +} +``` + +#### IBM - OpenWhisk - Web Action Event + +``` +{ + "__ow_method": "post", + "__ow_headers": { + "accept": "*/*", + "connection": "close", + "content-length": "4", + "content-type": "text/plain", + "host": "172.17.0.1", + "user-agent": "curl/7.43.0" + }, + "__ow_path": "", + "__ow_body": "Jane" +} +``` + +#### OpenStack - Audit Middleware - Event + +``` +{ + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + "id": "d8304637-3f63-5092-9ab3-18c9781871a2", + "eventTime": "2018-01-30T10:46:16.740253+00:00", + "action": "delete", + "eventType": "activity", + "outcome": "success", + "reason": { + "reasonType": "HTTP", + "reasonCode": "204" + }, + "initiator": { + "typeURI": "service/security/account/user", + "name": "user1", + "domain": "domain1", + "id": "52d28347f0b4cf9cc1717c00adf41c74cc764fe440b47aacb8404670a7cd5d22", + "host": { + "address": "127.0.0.1", + "agent": "python-novaclient" + }, + "project_id": "ae63ddf2076d4342a56eb049e37a7621" + }, + "target": { + "typeURI": "compute/server", + "id": "b1b475fc-ef0a-4899-87f3-674ac0d56855" + }, + "observer": { + "typeURI": "service/compute", + "name": "nova", + "id": "1b5dbef1-c2e8-5614-888d-bb56bcf65749" + }, + "requestPath": "/v2/ae63ddf2076d4342a56eb049e37a7621/servers/b1b475fc-ef0a-4899-87f3-674ac0d56855" +} +``` + +[Documentation](https://github.com/openstack/pycadf/blob/master/doc/source/event_concept.rst) + +#### Adobe - I/O Events + +``` +{ + "event_id": "639fd17a-d0bb-40ca-83a4-e78612bce5dc", + "event": { + "@id": "82235bac-2b81-4e70-90b5-2bd1f04b5c7b", + "@type": "xdmCreated", + "xdmEventEnvelope:objectType": "xdmAsset", + "activitystreams:to": { + "xdmImsUser:id": "D13A1E7053E46A220A4C86E1@AdobeID", + "@type": "xdmImsUser" + }, + "activitystreams:generator": { + "xdmContentRepository:root": "https://cc-api-storage.adobe.io/", + "@type": "xdmContentRepository" + }, + "activitystreams:actor": { + "xdmImsUser:id": "D13A1E7053E46A220A4C86E1@AdobeID", + "@type": "xdmImsUser" + }, + "activitystreams:object": { + "@type": "xdmAsset", + "xdmAsset:asset_id": "urn:aaid:sc:us:4123ba4c-93a8-4c5d-b979-ffbbe4318185", + "xdmAsset:asset_name": "example.jpg", + "xdmAsset:etag": "6fc55d0389d856ae7deccebba54f110e", + "xdmAsset:path": "/MyFolder/example.jpg", + "xdmAsset:format": "image/jpeg" + }, + "activitystreams:published": "2016-07-16T19:20:30+01:00" + } +} +``` + +[Documentation](https://www.adobe.io/apis/cloudplatform/events/documentation.html) From dfd81a46e1cb7918c76acc113cdf3e884452e43d Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:54:13 +0800 Subject: [PATCH 28/60] Delete primer_CN.md --- primer_CN.md | 704 --------------------------------------------------- 1 file changed, 704 deletions(-) delete mode 100644 primer_CN.md diff --git a/primer_CN.md b/primer_CN.md deleted file mode 100644 index 5b5b77bc6..000000000 --- a/primer_CN.md +++ /dev/null @@ -1,704 +0,0 @@ -# CloudEvents 入门文档 - 1.0 版本 - -Declaration： This manual aims to provide a fast and brief introduction of CloudEvents -in Chinese for people who are new to CloudEvents. -Most of the content is translated from the original English version. -It is strongly recommended to read the English version if you find anything lost in translation. - -## 摘要 - -这份非技术规范文档用来为你提供关于CloudEvents规范的总体概览。它补充了CloudEvents规范的相关背景 -以及在制定 本规范时的历史和设计理念。这样，CloudEvents的核心规范就只需要关注Events规范的技术细节， -而不用过多地关心背景相关内容。 - -## 目录 - -- [历史](#历史) -- [CloudEvents 概念](#CloudEvents-概念) -- [设计目标](#设计目标) -- [架构](#架构) -- [属性版本控制](#属性版本控制) -- [CloudEvent 属性](#CloudEvent-属性) -- [CloudEvent 属性扩展](#CloudEvent-属性扩展) -- [生产 CloudEvents](#生产CloudEvents) -- [合格的协议与编码](#合格的协议与编码) -- [专有的协议和编码](#专有的协议与编码) -- [现有技术](#现有技术) -- [角色](#角色) -- [价值主张](#价值主张) -- [现有的数据格式](#现有的数据格式) - -## 历史 - -[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 是由 CNCF的 -[技术监管委员会](https://github.com/cncf/toc) 成立，用于研究 -Serverless相关技术并为CNCF推荐相关领域的未来发展计划的。工作组其中一项建议就是研究创建一种通用事件格式， -用于提升不同云厂商间函数的可移植性和事件流处理的互操作性。就此，CloudEvents应运而生。 - -尽管CloudEvents起初是作为Serverless工作组的项目进行的，但随着CloudEvents规范完成它v0.1版本的里程碑， -技术监管委员会批准了CloudEvents作为一个新的独立的CNCF沙箱级项目。 - -## CloudEvents-概念 - -一个[事件](spec_CN.md#事件)包含了[事件发生](spec_CN.md#发生)的上下文和相关数据。 -事件的相关数据可以用来唯一标识一件事件的发生。 - -事件代表了已发生的事实，因此它并不包含任何目的地相关信息，但消息能够传达事件内容，从而将事件数据 -从源头传输到指定的目的地。 - -### 事件使用 - -事件通常在服务器端代码中使用来连接不同的系统，其中一个系统中的状态变化会导致代码在另一个系统中执行。 -比如，一个事件源，可能会在收到某个外部信号(如HTTP或RPC)或观察到状态变化(如IoT传感器数据变化或不活跃) -时，生产一个事件。 - -为了更好地解释一个系统如何使用CloudEvents，下图展示了一个从事件源生产的事件是如何触发一个行为的。 - -![alt text](source-event-action.png "A box representing the source with -arrow pointing to a box representing the action. The arrow is annotated with -'e' for event and 'protocol'.") - -事件源生产了一条封装了基于某种协议的事件数据的消息。 -当载有事件的消息到达目的地时，会触发一个使用了事件数据的行为函数。 - -一个事件源是那些允许暂存和测试实例的源类型的特定实例。 -某个特定源类型的开源软件可能由多个公司或提供商部署。 - -事件可以通过各种行业标准协议（如HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或 -平台/供应商专有协议（AWS Kinesis、Azure Event Grid）传输。 - -一个操作函数能够处理那些定义了行为或影响的事件，这些行为和效果由来自特定源的特定事件触发而来。 -虽然超出了规范的范围，但生成事件的目的通常是让其他系统能够轻松地对它们无法控制的源中的更改做出反应。 -源和操作通常由不同的开发人员构建。 -通常，源是托管服务，而操作是serverless函数（如 AWS Lambda 或 Google Cloud Functions）中 -的自定义代码。 - -## 设计目标 - -CloudEvents 通常用于分布式系统，以允许服务在开发过程中松耦合，独立部署，方便之后连接以创建新的应用程序。 - -CloudEvents 规范的目标是定义允许服务生产或消费事件的事件系统的互操作性， -其中生产者和消费者可以独立开发和部署。 生产者可以在没有消费者监听时就生成事件， -消费者也可以表达对尚未生成的事件或事件类的兴趣。值得注意的是，这项工作产生的规范侧重于事件格式的互操作性 -以及它在通过各种协议（例如 HTTP）发送时的显示方式。我们不关注事件生产者或事件消费者的处理模型。 - -CloudEvents的核心规范中定义了一组称之为属性的元数据， -它们描述了在系统之间传输的事件以及这些元数据片段应如何显示在该消息中。 -这些元数据是，将请求路由到适当组件并帮助该组件正确处理事件所需的最小信息集。 -因此，某些事件本身的数据可能会作为 CloudEvent 属性集的一部分而被复制， -但这样做仅是为了能够正确传递和处理消息。那些不用于该目的的数据应放置在事件（数据）本身中。 - -此外，本规范中假设协议层所需的用来将消息传递到目标系统的元数据应完全由协议处理， -因此不包含在 CloudEvents 属性中。 有关更多详细信息，请参阅[非目标](#非目标)部分。 - -除了这些属性的定义之外，规范还描述了关于如何序列化 -不同格式（例如 JSON）和协议（例如 HTTP、AMQP、Kafka）的事件。 - -一些协议本身支持将多个事件批处理到单个 API 的调用中。 -为了提升系统间的互操作性，是否以及如何实现批处理将由协议自己决定。 -相关详细信息可以在协议绑定或协议规范中找到。 -成批的CloudEvents并没有语义，也没有排序。 -[中间人](spec_CN.md#中间人)可以添加或删除批处理以及将事件分配给不同的批处理。 - -### 非目标 - -以下内容不在本规范的范围之内： - -- 函数的构建和调用过程 -- 特定语言的运行时 APIs -- 选择单一身份认证或访问控制的系统 -- 包含协议级路由信息 -- 事件持久化过程 - -就连那些刚接触 CloudEvents 概念的人都会建议 -CloudEvents 规范不应包括协议级路由信息（例如，将事件发送到的目标的URL）。 -经过深思熟虑，工作组得出的结论是，CloudEvents规范中不需要路由信息： -因为任何现有的协议（例如 HTTP、MQTT、XMPP 或 Pub/Sub 总线）都已经定义了路由语义。 -例如，CloudEvents [HTTP 绑定](http-protocol-binding.md) 规定了头部和请求正文内容。 -CloudEvents 不需要在规范中包含目标 URL 即可与 HTTP 兼容；HTTP 规范已经在 -[请求行](https://tools.ietf.org/html/rfc2616#section-5.1) 中包含了所需的目标URL。 - -路由信息不仅是多余的，而且是有害的。 -CloudEvents 应该增加互操作性并解耦事件的生产者和消费者。 -禁止来自事件格式的路由信息允许将 CloudEvents 重新传送到新的行为，或通过包含多个通道的复杂中继传送。 -例如，如果 Webhook 地址不可用，则用于 Webhook 的 CloudEvent 应可传送到死信队列。 -死信队列应该能够将事件传送给原始事件发射者从未想象过的新的行为上。 - -在系统内和跨系统生产和消费的 CloudEvent能够触发产生价值的行为。 -因此，对于调试或复制的目的而言，存档和或重放事件可能很有价值。 -但是，持久化事件会删除传输期间可用的上下文信息，例如生产者的身份和权利、保真验证机制或机密性保护。 -此外，持久化会增加满足用户需求的复杂性和挑战。 -例如，出于加密或签名目的重复使用私钥会增加攻击者可用的信息，从而降低安全性。 -因此我们推测，可以定义有助于满足持久性要求的属性，但这些属性可能随着行业最佳实践和进步而不断发展。 - -## 架构 -CloudEvents 规范集定义了四种有助于形成分层架构模型的不同类型的协议元素。 -基本规范定义了一个抽象信息模型，该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 - -1. [基本规范](spec_CN.md) 定义了一个抽象信息模型， - 该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 -2. [扩展属性](./spec_CN.md#扩展上下文属性) - 添加了特定于用例且可能重叠的扩展属性集和相关规则，如支持不同的追踪标准的规则。 -3. 事件格式编码,如 [JSON](json-format.md), 定义了基本规范的信息模型与所选扩展的编码方式， - 以将其映射到应用程序协议的头部和负载元素。 -4. 协议绑定, 如. [HTTP协议绑定](http-protocol-binding.md), - 在HTTP to HTTP的情况下， - 定义了 CloudEvent 如何绑定到应用程序协议的传输层 。 - 协议绑定不限制传输层的使用方式，这意味着 HTTP绑定可用于任何 HTTP方法以及请求和响应消息。 - -为了确保更广泛的互操作性，CloudEvents规范集为使用专有应用协议的事件传输提供了特定约束。 -[HTTP Webhook](http-webhook.md)规范并非特定于 CloudEvents， -而是可用于将任何类型的单向事件和通知发布到符合标准的 HTTP 端点。 -但是，由于其他地方缺乏此类规范，因此 CloudEvents 需要对其进行定义。 - -### 协议错误处理 - -CloudEvents 规范在很大程度上并未规定与 CloudEvents 的创建或处理相关联的处理模型。 -因此，如果在处理 CloudEvent 过程中出现错误， -请使用正常的协议级错误处理机制进行处理。 - -## 属性版本控制 - -对于某些 CloudEvents 属性，由其值引用的实体或数据模型可能会随时间变化。 -例如，`dataschema`可能引用模式文档的一个特定版本。 -通常，这些属性值会通过将一些特定于版本的字符串作为其值的一部分来区分每个变体。 -例如，可能会加入版本号 (v1, v2) 或日期 (2018-01-01)来区分。 - -CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强制使用版本字符串。 -是否使用完全取决于每个事件生产者。 -但是，当使用特定版本的字符串时，每当其值发生变化时都应注意， -因为事件消费者可能依赖于现有值，因此更改可能被解释为“破坏性更改”。 -应该在生产者和消费者之间建立某种形式的通信，以确保事件消费者知道能使用哪些可能的值。 -通常，这也适用于所有 CloudEvents 属性。 - -## CloudEvent-属性 - -本节介绍了与CloudEvent 属性相关的其他背景和设计要点。 - -### id - -`id` 属性是一个在同一事件源下所有事件中用来标识事件唯一的值 -（其中每个事件源由其 CloudEvents `source`属性唯一标识）。 -虽然`id`使用的确切值是生产者定义的， -但必须要确保来自单个事件源的 CloudEvents 消费者不会有两个事件共享相同的 id 值。 -唯一的例外是如果支持事件的重播，在这些情况下，可以使用 id 来检测这一点。 - -由于一次事件的发生可能导致生成多个cloud event， -在所有这些事件都来自同一事件源的情况下， -生成的每个 CloudEvent 将具有唯一的 `id`。 -以创建数据库条目为例，这一事件的发生可能会生成一个类型为 create 的 CloudEvent -和一个类型为 write 的 CloudEvent。 -这两个 CloudEvents 各自都有一个唯一的 ID。 -如果需要在这两个 CloudEvent 之间建立某种关联以表明它们都与同一事件相关， -那么可以使用 CloudEvent 中的一些附加数据来实现该目的。 - -从这方面来看，虽然事件生产者对`id`的使用可能是某个随机字符串， -或者在其它上下文中具有某种语义的字符串， -但对于此 CloudEvent 属性而言，这些含义并不成立， -因此本规范不建议将 `id` 用于除了唯一性检查之外的其它目的。 - -## CloudEvent-属性扩展 - -为了实现规范的设计目标， -规范作者将尝试限制他们在 CloudEvents 中定义的元数据属性的数量。 -为此，该项目定义的属性将分为以下三类： - -- 必要属性 -- 可选属性 -- 扩展属性 - -正如类别名称所暗示的那样， -“必要”属性是工作组认为在任何情况下，对所有事件都至关重要的属性， -而“可选”属性将在大多数情况下使用。 这些情况下的两个属性都在本规范中定义了出来。 - -工作组考虑到某些属性不够常见而不能归入上述两个类别， -但此类属性的良好定义仍会使系统间的互操作性级别受益， -因此将这些属性放入了“扩展”类别并记录在[扩展文档](documented-extensions.md)中， -本规范定义了这些扩展属性在 CloudEvent 中的显示方式。 - -在确定提议的属性属于哪个类别时， -工作组使用现有的用例和用户故事来解释它们的基本原理和需求。 -相关信息将添加到本文档的[现有技术](#现有技术)部分。 - -CloudEvent 规范的扩展属性是需要包含的附加元数据，它们能确保正确的路由和正确处理CloudEvent。 -用于其它目的的附加元数据， -即那些与事件本身相但在 CloudEvent 的传输或处理中不需要的元数据， -应改为放置在事件 (`data`)的扩展点内。 - -扩展属性应保持最少，以确保 CloudEvent 可以正确序列化和传输。 -事件生产者应该考虑在向 CloudEvent 添加扩展时可能遇到的技术限制。 -例如，[HTTP Binary Mode](http-protocol-binding.md#31-binary-content-mode) -使用 HTTP 头来传输元数据； -大多数 HTTP 服务器会拒绝包含过多 HTTP 头部数据的请求，要求限制其低至 8kb。 -因此，扩展属性的大小和数量应保持最小。 - -如果扩展变得流行，那么规范作者可能会考虑将其作为核心属性移入规范。 -这意味着在正式将新属性添加到规范之前，扩展机制/过程可用作审查新属性的一种方式。 - -### JSON 扩展 - -如 [CloudEvents JSON 事件格式](json-format.md)中 -[属性](json-format.md#2-attributes)部分所述， -CloudEvent 扩展属性与已定义属性(必要属性、可选属性)在序列化时处于同一等级 - -也就是说，它们都是 JSON 对象的顶层属性。 -CloudEvent的作者花了很长时间考虑所有选项，并认为这是最好的选择。 -理由如下： - -由于CloudEvents规范遵循 [semver](https://semver.org/) ， -这意味着只要新属性是可选属性，它们可以在核心规范的未来版本定义，而无需更改当前主要版本。 -在这样的情况下，请考虑现有消费者将如何使用新的（未知的）顶级属性。 -虽然消费者可以随意忽略它，因为它是可选的， -但在大多数情况下，这些属性仍然希望向接收这些事件的应用程序公开。 -这可能导致这些应用程序在基础设施不支持的情况下，支持这些属性。 -这意味着未知的顶级属性（无论是谁定义的——规范的未来版本或事件生产者）可能不会被忽略。 -因此，虽然其它一些规范定义了放置扩展的特定属性（例如顶级`extensions`属性）， -但作者认为在传入事件中具有两个不同位置的未知属性可能会导致互操作性问题和开发人员的混淆。 - -扩展属性通常用于测试那些被规范正式采用之前的潜在属性。 -如果有一个`extensions`类型的属性，这个新属性已经被序列化， -那么如果该属性被核心规范采用，它将从`extensions`属性提升（从序列化的角度）为顶级属性。 -如果我们假设这个新属性是可选的，那么当它被核心规范采用时， -它只是一个小版本增量，所有现有的消费者仍然会继续工作。 -但是，消费者将不知道此属性将出现在何处 - 在扩展属性中还是作为顶级属性。 -这意味着他们可能需要同时查看两个地方。 -如果属性出现在两个地方但具有不同的值怎么办？ -生产者是否需要将它放在两个地方，因为他们可能同时有新、老消费者？ -虽然可以为如何解决出现的每个潜在问题而制定明确的规则， -但作者认为一个避免这些问题的更好的办法是在序列化中只有一个位置来放置未知的甚至是新的属性。 -作者还注意到 HTTP 规范现在遵循类似的模式，不再建议扩展 HTTP 头部以 X- 为前缀。 - -## 生产CloudEvents - -CloudEvents 规范有意避免将CloudEvents 的创建方式设计的过于死板。 -例如，它不假定原始事件源必须是该事件生产对应 CloudEvent 的同一实体。 -这允许多种实现方式。 -但是，对于规范的实现者来说，理解规范作者心中的期望还是有帮助的，因为这将有助于确保互操作性和一致性。 - -如上所述，生成初始事件的实体是否与创建相应 CloudEvent 的实体相同是由实现决定的。 -但是，当构建/填充 CloudEvents 属性的实体代表事件源进行操作时，这些属性的值是用来描述事件或事件源， -而不是计算 CloudEvent 属性值的实体的。 -换句话说，当事件源和 CloudEvents 生产者之间的分离对事件使用者没有实质性意义时， -规范定义的属性通常不会包含任何值来指示这种职责分离。 - -这并不是说 CloudEvents 生产者不能向 CloudEvent 添加一些额外的属性， -但这些属性超出了规范的互操作性定义属性的范围。 -这类似于 HTTP 代理通常如何最大限度地减少对传入消息的明确定义的 HTTP 头部的更改， -但它可能会添加一些额外的头部，其中包括一些特定代理的元数据。 - -还值得注意的是，原始事件源和 CloudEvents 生产者之间的这种分离可大可小。 -意思是，即使 CloudEvent 生产者不是原始事件源生态系统的一部分， -如果它代表事件源行事，并且它在事件流中的存在对事件消费者没有意义，那么上述指导仍然适用。 - -当实体同时充当 CloudEvents 的接收者和发送者以转发或转换传入事件时， -出站 CloudEvent 与入站 CloudEvent 匹配的程度将根据该实体的处理语义而有所不同。 -在它充当代理的情况下，它只是将 CloudEvents 转发给另一个事件消费者， -那么出站 CloudEvent 通常看起来与入站 CloudEvent 就规范定义的属性相同 -- 请参阅上一段有关添加其他属性的内容。 - -但是，如果此实体正在执行 CloudEvent 的某种类型的语义处理， -通常会导致`data`属性值发生更改， -则可能需要将其视为与原始事件源不同的“事件源”。 -因此，与事件生产者相关的 CloudEvents 属性（例如`source` and `id`） -将从传入的 CloudEvent 中更改。 - -## 合格的协议与编码 - -正如规范中所表达的，CloudEvents 工作的明确目标是 -“以通用方式描述事件数据”且 -“定义允许服务产生或消费事件的事件系统的互操作性，其中生产者和消费者可以被独立开发和部署”。 - -这种互操作性的基础是开放的数据格式和协议， -CloudEvents 旨在提供这种开放的数据格式，并将其数据格式映射到常用协议和常用编码上。 - -虽然每个软件或服务产品和项目都可以自己选择自己喜欢的通信形式， -但毫无疑问，这种产品或项目私有的专有协议无法进一步实现跨生产者和消费者的广泛互操作性的目标。 - -特别是在消息传递和事件处理领域，该行业在过去十年中开发出了强大且受到广泛支持的协议 -例如 HTTP 1.1 和 HTTP/2 以及 WebSockets 或 Web 上的事件，或者 MQTT 和 AMQP -用于面向连接的消息传递和遥测传输的协议。 - -一些广泛使用的协议已经成为事实上的标准，这些协议来自三个或更多公司的顶级财团打造的强大生态系统， -还有一些来自单个公司发布的强大项目生态系统，在任何一种情况下都与前面提到的标准栈的演变相一致。 - -CloudEvents的努力不应成为认可或推广项目或产品专有协议的工具， -因为这与CloudEvents 的原始目标背道而驰。 - -要使协议或编码符合核心 CloudEvents 事件格式或协议绑定的条件，它必须属于以下任一类别： - -- 该协议具有广泛认可的多供应商协议标准化机构（例如 W3C、IETF、OASIS、ISO）的正式标准地位 -- 该协议在其生态系统类别中具有“事实上的标准”地位， - 这意味着它被广泛使用，甚至被认为是给定应用程序的标准。 - 实际上，我们希望在供应商中立的开源组织（例如 Apache、Eclipse、CNCF、.NET 基金会）的保护伞下 - 看到至少一个开源实现， - 并且至少有十几个独立供应商在他们的产品中使用它的产品或服务。 - -除了正式状态之外，协议或编码是否符合核心 CloudEvents 事件格式或协议绑定的一个关键标准是， -该组织是否认为协议或编码出现后，该规范对与产品或项目无关的任何一方具有持续的实际利益。 -对此的基本要求是协议或编码的定义方式允许独立于产品或项目代码的替代实现。 - -欢迎将 CloudEvents 的所有其他协议和编码格式 -包含在指向相应项目自己的公共仓库，或站点中的 CloudEvents binding信息的列表中。 - -## 专有的协议与编码 - -为了鼓励更多人采用 CloudEvents，本仓库将自动收集专有协议和编码。 -本仓库的维护人员不负责创建、维护或通知专有规范的维护人员有关专有规范和CloudEvents规范间的偏差。 - -专有规范将托管在他们自己的仓库或文档站点中，并记录在[专有规范](proprietary-specs.md) -文件中。 专有规范应遵循与核心协议和编码相关的其他规范相同的格式。 - -专有规范将比核心规范受到更少的审查，并且随着 CloudEvents 规范的发展， -相应协议和编码的维护者有责任使规范与 CloudEvents 规范保持同步。 -如果专有规范过时太多，CloudEvents 可能会将指向该规范的链接标记为已弃用或将其删除。 - -如果为同一个协议创建了多个不兼容的规范，存储库维护者将不知道哪个规范是正确的，并列出所有规范的链接。 - -## 现有技术 - -本节介绍了工作组在 CloudEvent 规范开发过程中使用的一些输入材料。 - -### 角色 - -下面列举了可能涉及事件的产生、管理或消费的各种参与者和场景。 - -在这些中，事件生产者和事件消费者的角色是不同的。 -单个应用程序上下文背景始终可以同时承担多个角色，包括既是事件的生产者又是事件的消费者。 - -1. 应用程序生成供他人使用的事件， - 如为消费者提供有关终端用户活动、状态变化或环境观察的见解， - 或允许通过事件驱动的扩展来补充应用程序的功能。 - - 生产的事件通常与上下文或生产者选择的分类相关。 - 例如，房间中的温度传感器可能被安装位置、房间、楼层和建筑物等上下文限定。 - 运动结果可以按联赛和球队分类。 - - 生产者应用程序可以在任何地方运行，例如在服务器或设备上。 - - 生产的事件可能由生产者或中间人直接提供和发出； - 作为后者的示例，请考虑设备通过负载大小受限的网络（如 LoRaWAN 或 ModBus）传输的事件数据， - 并且符合此规范的事件将由网络网关代表生产者提供。 - - 例如，气象站每 5 分钟通过 LoRaWAN 传输一次 12 字节的专有事件payload用于指示天气状况。 - 然后使用 LoRaWAN 网关以 CloudEvents 格式将事件发布到 Internet 目标。 - LoRaWAN 网关是事件生产者，代表气象站发布事件，并将设置一定的元数据以反映事件的来源(气象站)。 - -2. 应用程序可能以以下目的： - 如显示、存档、分析、工作流处理、监控状态或提供业务解决方案及其基本构建模块的透明化 - 来消费事件。 - - 消费者应用程序可以在任何地方运行，例如在服务器或设备上。 - - 消费应用程序通常对以下内容感兴趣： - - - 区分事件，使得完全相同的事件不会被处理两次。 - - 识别和选择源上下文或生产者指定的分类。 - - 确定事件相对于原始上下文或相对于时钟的时间顺序。 - - 了解事件中携带的上下文相关的详细信息。 - - 关联来自多个事件生产者的事件实例并将它们发送到相同的消费者上下文。 - - 在某些情况下，消费应用程序可能对以下内容感兴趣： - - - 从原始上下文中获取有关事件主题的更多详细信息，例如获取有关需要特权访问授权的已更改对象的详细信息。 - 例如，出于隐私原因，HR 解决方案可能仅在事件中发布非常有限的信息， - 任何需要更多数据的事件消费者都必须在其自己的授权上下文背景下从 HR 系统获取与事件相关的详细信息 - - 在原始上下文中与事件的主题进行交互，例如在被告知该数据块刚刚创建后读取存储该数据块。 - - 消费者的兴趣激发了信息生产者应该包括事件的需求。 - -3. 中间件将事件从生产者路由到消费者，或转发到其他中间件。 - 产生事件的应用程序可能会将根据消费者需求产生的某些任务委托给中间件： - - - 管理同时对大量类别和上下文背景中的某个事件感兴趣的消费者。 - - 代表消费者在类或事件的原始上下文上处理过滤条件。 - - 转码，比如从 JSON 解码后在 MsgPack 中编码。 - - 更改事件结构的转换，例如从专有格式映射到 CloudEvents，同时保留事件的身份和语义完整性。 - - 即时“推送式”传输给感兴趣的消费者。 - - 存储最终传输的事件，用于由消费者发起的“拉”请求，或延迟后由中间件发起“推”请求。 - - 观察事件内容或事件流以进行监控或诊断。 - - 为了满足这些需求，中间件将对以下方面感兴趣： - - - 一种元数据鉴别器，可用于事件的分类或上下文化，以便消费者可以表达对一个或多个类或上下文的兴趣。 - 例如，消费者可能对文件存储帐户内的特定目录相关的所有事件感兴趣。 - - 一种元数据鉴别器，允许区分该类或上下文的特定事件的主题。例如，消费者可能希望过滤掉与以“.jpg”结尾的 - 新文件相关的所有事件（文件名是“新文件”事件的主题），以此表示它对感兴趣的文件存储账户下某个目录的 - 上下文环境。 - - 一个事件及其数据编码的指示器。 - - 一个事件及其数据的结构布局（模式）的指示器。 - - 事件是否可通过中间件消费取决于生产者的选择。 - - 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec_CN.md#生产者)的角色， - 当它根据事件采取行动时可以扮演[消费者](spec_CN.md#消费者)的角色， - 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec_CN.md#中间人)的角色。 - -4. 框架和其他抽象使与事件平台基础设施间的交互更简单， - 并且通常为多个事件平台基础设施提供公共 API 区域。 - - 框架通常用于将事件转换为对象图，并将事件分派给某些特定的处理逻辑或用户规则， - 这些用户逻辑或用户规则允许消费应用程序对原始上下文和特定主题中的特定类型的事件做出反应。 - - 框架最感兴趣的是跨抽象平台的语义元数据通用性，以便可以统一处理类似的活动。 - - 对于体育应用程序，使用该框架的开发人员可能对联盟中一支球队今天的比赛（主题） - 的所有事件感兴趣，但希望以不同于“换人”事件的方式处理“得分”事件。 - 为此，框架将需要一个合适的元数据鉴别器，使其不必了解事件细节。 - -### 价值主张 - -本节介绍了一些能够展示 CloudEvents 价值主张的用例。 - -#### 跨服务和平台规范化事件 - -主要事件发布者（例如 AWS、Microsoft、Google 等）都在各自的平台上以不同的格式发布事件。 -甚至在少数情况下，同一提供商的服务以不同格式（例如 AWS）发布事件。 -这迫使事件消费者实现自定义逻辑以跨平台读取或处理事件数据，有时甚至需要跨单个平台的多个服务处理。 - -CloudEvents 可以为那些跨平台和服务处理事件的使用者提供单一体验。 - -#### 促进跨服务和平台的集成 - -跨环境传输的事件数据越来越普遍。 -然而，如果没有描述事件的通用方式，跨环境的事件传递就会受到阻碍。 -CloudEvents之前没有单一的方法可以确定事件的来源和可能的去向。 -这对研究成功传输事件事件工具和消费者知道如何处理事件数据形成了巨大阻碍。 - -CloudEvents 提供有用的元数据，中间件和消费者可以依赖这些元数据来促进事件路由、日志记录、传输和接收。 - -#### 提高功能即服务的可移植性 - -功能即服务（也称为serverless计算）是 IT 中增长最快的趋势之一，它主要是由事件驱动的。 -然而，FaaS 的一个主要问题是供应商锁定。 -这种锁定部分是由函数 API 和供应商之间签名的差异引起的， -锁定同样也是由函数内接收的事件数据格式的差异引起的。 - -CloudEvents提供描述事件数据的通用方式提高了功能即服务的可移植性。 - -#### 改进事件驱动/serverless架构的开发和测试 - -缺乏通用事件格式使事件驱动和serverless架构的开发和测试变得复杂。 -没有简单的方法可以准确地为开发和测试目的模拟事件，并帮助在开发环境中模拟事件驱动的工作流。 - -CloudEvents 可以提供更好的开发工具来构建、测试和处理事件驱动和无服务器架构的端到端生命周期。 - -#### 事件数据发展 - -大多数平台和服务对其事件的数据模型进行不同的版本控制（如果他们这样做的话）。 -随着这些数据模型的发展，这会为发布和使用事件的数据模型带来不一致的体验。 - -CloudEvents 可以提供一种通用的方式来版本化和演化事件数据的发展。 -这将帮助事件发布者根据最佳实践安全地对其数据模型进行版本控制， -并且这有助于事件消费者随着事件数据的发展安全地使用它。 - -#### 规范化 Webhook - -Webhooks 是一种不使用通用格式的来发布事件的模式。 -Webhook 的使用者没有一致的方式来开发、测试、识别、验证和整体处理通过 Webhook 传输的事件数据。 - -CloudEvents 可以提供 Webhook 发布和消费事件的一致性。 - -#### 安全策略 - -出于安全和策略考虑，可能需要过滤、转换或阻止系统之间的事件传输。 -比如可能需要防止事件的进入或退出，如包含敏感信息的事件数据或想要禁止发送方和接收方之间的信息流。 - -通用事件格式将允许更容易地推理正在传输的数据，并提供更好的数据自查。 - -#### 事件追踪 - -从源发送的事件可能会出现在一系列附加事件序列之中， -这些附加事件序列从各种中间件设备（例如事件代理和网关）发出。 -CloudEvents 在事件中包含元数据以将这些事件关联为事件序列的一部分，以便进行事件跟踪和故障排除。 - -#### IoT - -物联网设备会发送和接收与其功能相关的事件。 -例如，连接的恒温器将发送有关当前温度的遥测数据， -并可以接收改变温度的事件。 -这些设备通常具有受限的操作环境（cpu、内存），需要明确定义的事件消息格式。 -在很多情况下，这些消息是二进制编码的，而不是文本的。 -无论是直接来自设备还是通过网关转换，CloudEvents 都可以更好地描述消息的来源和消息中包含的数据格式。 - -#### 事件关联 - -一个serverless应用或工作流可能与来自不同事件源或事件生产者的多个事件相关联。 -例如，盗窃检测应用程序/工作流可能涉及运动事件和门/窗打开事件。 -一个serverless平台可能接收每种类型事件的许多实例，例如 它可以接收来自不同房屋的运动事件和开窗事件。 - -serverless平台需要将一种类型的事件实例与其他类型的事件实例正确关联， -并将接收到的事件实例映射到正确的应用/工作流实例。 -CloudEvents 将为任何事件使用者（例如serverless平台）提供一种标准方式， -以在事件数据中定位事件关联信息/令牌并将接收到的事件实例映射到正确的应用/工作流实例。 - -### 现有的数据格式 - -与上一节一样，对当前现状的调查（和理解）对CloudEvents 小组来说非常重要。 -为此，下面列出了在实践中被广泛使用的当前事件格式的样本。 - -#### Microsoft - Event Grid - -``` -{ - "topic":"/subscriptions/{subscription-id}", - "subject":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/eventSubscriptions/LogicAppdd584bdf-8347-49c9-b9a9-d1f980783501", - "eventType":"Microsoft.Resources.ResourceWriteSuccess", - "eventTime":"2017-08-16T03:54:38.2696833Z", - "id":"25b3b0d0-d79b-44d5-9963-440d4e6a9bba", - "data": { - "authorization":"{azure_resource_manager_authorizations}", - "claims":"{azure_resource_manager_claims}", - "correlationId":"54ef1e39-6a82-44b3-abc1-bdeb6ce4d3c6", - "httpRequest":"", - "resourceProvider":"Microsoft.EventGrid", - "resourceUri":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/eventSubscriptions/LogicAppdd584bdf-8347-49c9-b9a9-d1f980783501", - "operationName":"Microsoft.EventGrid/eventSubscriptions/write", - "status":"Succeeded", - "subscriptionId":"{subscription-id}", - "tenantId":"72f988bf-86f1-41af-91ab-2d7cd011db47" - } -} -``` - -[Documentation](https://docs.microsoft.com/en-us/azure/event-grid/event-schema) - -#### Google - Cloud Functions (potential future) - -``` -{ - "data": { - "@type": "types.googleapis.com/google.pubsub.v1.PubsubMessage", - "attributes": { - "foo": "bar", - }, - "messageId": "12345", - "publishTime": "2017-06-05T12:00:00.000Z", - "data": "somebase64encodedmessage" - }, - "context": { - "eventId": "12345", - "timestamp": "2017-06-05T12:00:00.000Z", - "eventTypeId": "google.pubsub.topic.publish", - "resource": { - "name": "projects/myProject/topics/myTopic", - "service": "pubsub.googleapis.com" - } - } -} -``` - -#### AWS - CloudWatch Events - -AWS 上的很大一部分事件处理系统都在使用这种格式。 - -``` -{ - "version": "0", - "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718", - "detail-type": "EC2 Instance State-change Notification", - "source": "aws.ec2", - "account": "111122223333", - "time": "2017-12-22T18:43:48Z", - "region": "us-west-1", - "resources": [ - "arn:aws:ec2:us-west-1:123456789012:instance/i-1234567890abcdef0" - ], - "detail": { - "instance-id": "i-1234567890abcdef0", - "state": "terminated" - } -} -``` - -#### IBM - OpenWhisk - Web Action Event - -``` -{ - "__ow_method": "post", - "__ow_headers": { - "accept": "*/*", - "connection": "close", - "content-length": "4", - "content-type": "text/plain", - "host": "172.17.0.1", - "user-agent": "curl/7.43.0" - }, - "__ow_path": "", - "__ow_body": "Jane" -} -``` - -#### OpenStack - Audit Middleware - Event - -``` -{ - "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", - "id": "d8304637-3f63-5092-9ab3-18c9781871a2", - "eventTime": "2018-01-30T10:46:16.740253+00:00", - "action": "delete", - "eventType": "activity", - "outcome": "success", - "reason": { - "reasonType": "HTTP", - "reasonCode": "204" - }, - "initiator": { - "typeURI": "service/security/account/user", - "name": "user1", - "domain": "domain1", - "id": "52d28347f0b4cf9cc1717c00adf41c74cc764fe440b47aacb8404670a7cd5d22", - "host": { - "address": "127.0.0.1", - "agent": "python-novaclient" - }, - "project_id": "ae63ddf2076d4342a56eb049e37a7621" - }, - "target": { - "typeURI": "compute/server", - "id": "b1b475fc-ef0a-4899-87f3-674ac0d56855" - }, - "observer": { - "typeURI": "service/compute", - "name": "nova", - "id": "1b5dbef1-c2e8-5614-888d-bb56bcf65749" - }, - "requestPath": "/v2/ae63ddf2076d4342a56eb049e37a7621/servers/b1b475fc-ef0a-4899-87f3-674ac0d56855" -} -``` - -[Documentation](https://github.com/openstack/pycadf/blob/master/doc/source/event_concept.rst) - -#### Adobe - I/O Events - -``` -{ - "event_id": "639fd17a-d0bb-40ca-83a4-e78612bce5dc", - "event": { - "@id": "82235bac-2b81-4e70-90b5-2bd1f04b5c7b", - "@type": "xdmCreated", - "xdmEventEnvelope:objectType": "xdmAsset", - "activitystreams:to": { - "xdmImsUser:id": "D13A1E7053E46A220A4C86E1@AdobeID", - "@type": "xdmImsUser" - }, - "activitystreams:generator": { - "xdmContentRepository:root": "https://cc-api-storage.adobe.io/", - "@type": "xdmContentRepository" - }, - "activitystreams:actor": { - "xdmImsUser:id": "D13A1E7053E46A220A4C86E1@AdobeID", - "@type": "xdmImsUser" - }, - "activitystreams:object": { - "@type": "xdmAsset", - "xdmAsset:asset_id": "urn:aaid:sc:us:4123ba4c-93a8-4c5d-b979-ffbbe4318185", - "xdmAsset:asset_name": "example.jpg", - "xdmAsset:etag": "6fc55d0389d856ae7deccebba54f110e", - "xdmAsset:path": "/MyFolder/example.jpg", - "xdmAsset:format": "image/jpeg" - }, - "activitystreams:published": "2016-07-16T19:20:30+01:00" - } -} -``` - -[Documentation](https://www.adobe.io/apis/cloudplatform/events/documentation.html) From 4e40b531db46d49d85790f25575415273aabbbef Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:55:01 +0800 Subject: [PATCH 29/60] Create spec_CN.md --- Chinese Manual/spec_CN.md | 478 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 478 insertions(+) create mode 100644 Chinese Manual/spec_CN.md diff --git a/Chinese Manual/spec_CN.md b/Chinese Manual/spec_CN.md new file mode 100644 index 000000000..e27e009d3 --- /dev/null +++ b/Chinese Manual/spec_CN.md @@ -0,0 +1,478 @@ +# CloudEvents 核心规范- 1.0 版本 + +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. + +## 摘要 + +CloudEvents 是一个用于定义事件格式的供应商中立规范。 + +## 目录 + +- [概览](#概览) +- [符号和术语](#符号和术语) +- [上下文属性](#上下文属性) +- [事件数据](#事件数据) +- [大小限制](#大小限制) +- [隐私与安全](#隐私与安全) +- [示例](#示例) + +## 概览 + +事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 + +对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。 +它同样限制了那些用来帮助事件数据完成 跨环境传输的库(如SDKs)， +工具(如事件路由器)和基础设施(如事件追踪系统)的发展。 +总体来看，这种匮乏严重阻碍了事件数据的可移植性和生产力。 + +CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 + +事件格式指定如何使用某些编码格式序列化一个 CloudEvent。 +支持那些编码且兼容 CloudEvents 的实现必须遵守相应事件格式中指定的编码规则。 +所有实现都必须支持 [JSON 格式](json-format.md)。 + +有关规范背后的历史、开发和设计原理等更多信息， +请参阅 CloudEvents [入门文档](primer_CN.md)。 + +## 符号和术语 + +### 符号约定 + +本文档中的关键词 +"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 需要按照 +[RFC 2119](https://tools.ietf.org/html/rfc2119) 中的描述来理解。 + +为清楚起见， +当一个功能被标记为“OPTIONAL”时，这意味着消息的 +[生产者](#生产者)和[消费者](#消费者) 都可以自行选择是否支持该功能。 +换句话说，生产者可以在需要时在消息中包含该功能，消费者也可以在需要时选择支持该功能。 +不支持该功能的消费者将默默地忽略该部分消息。 +生产者需要做好消费者并没有启用该功能的准备。 +[中间人](#中间人) 应当转发OPTIONAL属性。 + +### 术语 + +本规范定义了下列术语 + +#### 发生 + +“发生”是指在软件系统运行期间对事实状态的捕获。 +这可能是由于系统发出了信号或系统观察到信号、状态更改、计时器超时 +或任何其他值得注意的活动而发生的。 +例如，设备可能会因为电池电量低或虚拟机即将执行计划的重启而进入警报状态。 + +#### 事件 + +“事件”是表示一条"发生"及其上下文的数据记录。 +事件从事件生产者（源）路由到对它感兴趣的事件消费者。 +事件中包含的信息帮助完成路由操作，但事件不会标识特定的路由目的地。 +事件将包含两种类型的信息：表示"发生"的 [事件数据](#事件数据) +和提供有关事件的环境信息的[上下文](#上下文) 元数据。 +一次"发生"可能导致多个事件的产生。 + +#### 生产者 + +“生产者”是一种特定的实例、进程或设备，它能够创建用来描述CloudEvent的数据结构。 + +#### 源 + +"源"是事件发生的上下文环境。在分布式系统中，它可能由多个生产者组成。 +如果一个源无法查看到CloudEvents，那么一定有有外部的生产者在代替源来生产CloudEvent。 + +#### 消费者 + +一个“消费者”会接收事件并根据事件采取一定的行为。 +它使用上下文环境和事件数据来执行一些逻辑，这可能会导致新事件的发生。 + +#### 中间人 + +一个“中间人”会接收包含事件的消息， +并将其转发给下一个接收者，但该接收者可能是另一个中间人或事件[消费者](#消费者)。 +中间人的典型任务就是根据[上下文](#上下文)环境中的信息将事件路由到接收者。 + +#### 上下文 + +上下文环境元数据被封装在[上下文-属性](#上下文-属性)中。 +工具和应用程序代码可以使用此信息来识别事件与系统方面或事件与其他事件的关系。 + +#### 数据 + +关于事件的特定域信息（即有效负载）。这可能包括有关事件的信息、有关已更改数据的详细信息等。 +有关更多信息，请参阅[事件数据](#事件数据)部分。 + +#### 事件格式 + +一个事件格式会指定如何将 CloudEvent 序列化为字节序列。 +独立事件格式（例如 [JSON 格式](json-format.md)）指定独立于任何协议或存储介质的序列化。 +协议绑定可以定义依赖于协议的格式。 + +#### 消息 + +事件通过消息从源传输到目标。 + +“结构化模式消息”是一种使用独立事件格式对事件进行完全编码并存储在消息体中的消息。 + +“二进制模式消息”会将事件数据存储在消息体中，并将事件属性作为消息元数据的一部分存储下来。 + +#### 协议 + +消息可以通过各种行业标准协议 +（例如 HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或平台/供应商 +专有协议（AWS Kinesis、Azure 事件网格）传输。 + +#### 协议绑定 + +协议绑定描述了如何通过给定协议发送和接收事件，特别是如何将事件映射到该协议的消息中去。 + +## 上下文属性 + +每个符合本规范的 CloudEvent 必须包括指定为 REQUIRED 的上下文属性， +可以包括一个或多个OPTIONAL上下文属性， +并且可以包括一个或多个扩展属性。 + +这些属性虽然描述了事件，但被设计为可以独立于事件数据进行序列化。 +这允许在不反序列化事件数据的情况下，在目的检查这些上下文属性。 + +### 属性命名约定 + +CloudEvents 规范定义了到各种协议和编码的映射，随附的 CloudEvents SDK 面向各种运行时和编程语言。 +其中一些将元数据元素区分大小写，而另一些则不区分， +并且单个 CloudEvent 可能通过涉及到协议、编码和运行时混合的多个跃点进行路由。 +因此，本规范限制了所有属性的可用字符集，以防止区分大小写问题或与通用语言中标识符的合法字符集冲突问题。 + +CloudEvents 属性名称必须由来自 ASCII 字符集的小写字母（“a”到“z”）或数字（“0”到“9”）组成。 +属性名称应该是描述性的和简洁的，并且长度不应超过 20 个字符。 + +### 类型系统 + +以下抽象数据类型可用于属性。 +这些类型中的每一种都可以由不同的事件格式和协议元数据字段以不同的方式表示。 +本规范为所有实现必须支持的每种类型定义了规范的字符串编码。 + +- `Boolean` - “true”或“false”的布尔值。 + - 字符串编码：区分大小写的`true` 或 `false`值。 +- `Integer` -范围在 -2,147,483,648 到 +2,147,483,647 （包含）之间的整数。 + 这是有符号 32 位二进制补码编码的范围。 + 事件格式不必使用此编码，但它们必须使用在此范围内的`Integer` 值。 + - 字符串编码: 符合 + [RFC 7159, 第 6 节](https://tools.ietf.org/html/rfc7159#section-6) + JSON 数字的整数部分 +- `String` - 允许的 Unicode 字符序列。 不允许使用以下字符： + - 范围 U+0000-U+001F 和 U+007F-U+009F（包含首尾）中的“控制字符”， + 因为大多数没有商定的含义，还有一些，例如 U+000A（换行符）， 在如 HTTP 头部之类的上下文中不可用。 + -[被 Unicode 标识为非字符的](http://www.unicode.org/faq/private_use.html#noncharacters) + 代码点。 + - 被 Unicode 标识为代理项的代码点, 范围 U+D800-U+DBFF 和 U+DC00-U+DFFF（包含首尾） + , 除非被合理的用作代理对. 因此（在 JSON 符号中） + “\uDEAD”是无效的，因为它是一个未配对的代理，而“\uD800\uDEAD”是合法的。 +- `Binary` - 字节序列. + - 字符串编码: 基于 + [RFC4648](https://tools.ietf.org/html/rfc4648) 的Base64 编码。 +- `URI` - 绝对统一资源标识符。 + - 字符串编码: + [RFC 3986 第 4.3 节](https://tools.ietf.org/html/rfc3986#section-4.3) + 中定义的 `Absolute URI` 。 +- `URI-reference` - 统一资源标识符引用。 + - 字符串编码: + [RFC 3986 第 4.1 节](https://tools.ietf.org/html/rfc3986#section-4.1) + 中定义的`URI-reference` 。 +- `Timestamp` - 使用公历的日期和时间表达式。 + - 字符串编码: [RFC 3339](https://tools.ietf.org/html/rfc3339) 。 + +所有上下文属性值必须是上面列出的类型之一。 +属性值可以表示为原生类型或规范字符串。 + +当强类型编程语言表示 CloudEvent 或任何扩展时， +必须能够在规范字符串编码与对应抽象类型的运行时/编程语言类型之间进行转换。 + +例如，在给定的实现中，`time` 属性可能由编程语言的本地时间类型表示， +但它必须是可设置提供 RFC3339 字符串的， +并且当映射到 HTTP 消息头时，它必须可转换为 RFC3339 字符串。 + +CloudEvents 协议绑定或事件格式实现同样必须能够 +在规范字符串编码与协议元数据字段中的对应数据类型之间进行转换。 + +`Timestamp` 类型的属性值确实可能以字符串形式路由通过多个跃点， +并且仅在生产者和最终消费者处实现为本地运行时/语言类型。 +`Timestamp` 类型也可以作为本机协议类型路由， +并且可以在生产者和消费者端映射到/从各自的语言/运行时类型，但永远不会转为字符串格式。 + +序列化机制的选择将决定上下文属性和事件数据将如何序列化。 +例如，在 JSON 序列化的情况下，上下文属性和事件数据可能都出现在同一个 JSON 对象中。 + +### 必要属性 + +下列属性必须自所有的 CloudEvents 中展示： + +#### id + +- 类型: `String` +- 描述: 标识一个事件。 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 + 如果重复的事件被重新发送（例如由于网络错误），它可能具有相同的 `id`。 + Consumers MAY assume that + 消费者可以假设具有相同`source` 和 `id`的事件是重复的。 +- 示例: + - 一个由生产者维护的事件计数器 + - 一个 UUID +- 约束条件: + - 必要的 + - 必须是非空字符串 + - 在生产者的范围内必须是唯一的 + +#### source + +- 类型: `URI-reference` +- 描述: 标识事件发生的上下文背景。 这通常包括诸如事件源类型、发布事件的组织 + 或产生事件的过程等信息。URI 中编码的数据背后的确切语法和语义由事件生产者定义。 + + 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 + + 应用程序可以为每个不同的生产者分配一个唯一的`source`， + 这使得生成唯一 ID 变得容易，因为没有其他生产者将拥有相同的来源。 + 应用程序可以使用 UUIDs、URNs、DNS权威机构或特定于应用程序的方案来创建唯一的`source` 标识符。 + + 一个来源可以包括多个生产者。 + 在这种情况下，生产者必须协作以确保每个不同事件的 `source` + `id`都是唯一的。 + +- 约束条件: + - 必要的 + - 必须是非空 URI-reference + - 推荐使用 绝对 URI +- 示例 + - 具有 DNS 权限的 Internet 范围唯一 URI： + - https://github.com/cloudevents + - mailto:cncf-wg-serverless@lists.cncf.io + - 具有 UUID 的通用唯一 URN： + - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 + - 应用程序专有的标识符 + - /cloudevents/spec/pull/123 + - /sensors/tn-1234567/alerts + - 1-555-123-4567 + +#### specversion + +- 类型: `String` +- 描述: 事件使用的 CloudEvents 规范的版本。 + 这让解释上下文环境更容易。 + 当引用这个版本的规范时，兼容的事件生产者必须使用 `1.0` 的值。 +- 约束条件: + - 必要的 + - 必须是非空字符串 + +#### type + +- 类型: `String` +- 描述: 该属性包含一个值，描述与原始事件相关的事件类型。 + 该属性通常用于路由、可观察性、策略实施等。其格式是生产者定义的，可能包括诸如 `type`版本之类的信息 + -从 + [入门文档-属性版本控制](primer_CN.md#属性版本控制) 中获得更多信息 + +- 约束条件: + - 必要的 + - 必须是非空字符串 + - 应该以反向 DNS 名称作为前缀。该前缀域表明了定义此事件类型语义的组织。 +- 示例 + - com.github.pull.create + - com.example.object.delete.v2 + +### 可选属性 + +下列属性在 CloudEvents 中是可选的. 在 +[符号约定](#notational-conventions) 中查看更多 OPTIONAL 定义的信息。 + +#### datacontenttype + +- 类型: `String` [RFC 2046](https://tools.ietf.org/html/rfc2046) +- 描述: `data`值的内容类型。 此属性使`data`能够承载任何类型的内容， + 因此格式和编码可能与所选事件格式的不同。 + 例如，使用 [JSON envelope](./json-format.md#3-envelope) + 格式呈现的事件可能在数据中携带 XML 的payload，这个属性可以用来通知消费者 + 设置"application/xml"。 + 关于`data`内容如何提供不同的`datacontenttype`的值的规则在事件格式规范中定义。 + 例如，JSON 事件格式定义了 [3.1 节](./json-format.md#31-handling-of-data)中的关系。 + 对于某些二进制模式协议绑定， + 此字段直接能映射到相应协议的内容类型的元数据属性上。 + 二进制模式和内容类型元数据映射的规范规则可以在各自的协议中找到。 + + 在某些事件格式中，可以省略 `datacontenttype` 属性。 + 例如，如果 JSON 格式的事件没有 `datacontenttype` 属性， + 则表示该`data`是符合“application/json”媒体类型的 JSON 值。 + 换句话说：一个没有 `datacontenttype` 的 JSON 格式的事件完全等同于 + 一个带有 `datacontenttype="application/json"`的事件。 + + 当将没有 `datacontenttype` 属性的事件消息转换为不同的格式或协议绑定时， + 目标 `datacontenttype` 应该显式设置为事件源的隐含或默认的 `datacontenttype`。 + +- 约束条件: + - 可选的 + - 若有则必须遵守 + [RFC 2046](https://tools.ietf.org/html/rfc2046) 制定的格式 +- 媒体类型示例 + [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml) + +#### dataschema + +- 类型: `URI` +- 描述: 标识 `data` 遵守的规范。 对模式的不兼容的更改应该由不同的 URI 体现。 在 + [入门文档-属性版本控制](primer_CN.md#属性版本控制) + 中查看更多信息。 +- 约束条件: + - 可选的 + - 若有必须是非空的 URI + +#### subject + +- 类型: `String` +- 描述: 这个属性描述了事件生产者 (由`source`标识) 上下文环境中的主题信息。 + 在发布-订阅场景中，订阅者通常会订阅`source`发出的事件， + 但如果`source` 的上下文环境具有内部子结构， + 则单独的`source`标识符可能不足以作为任何指定事件的限定符。 + + 在上下文元数据中识别事件的主题（与仅在数据负载中相反） + 对于中间件无法解释`data` 内容的通用订阅过滤场景特别有用。 + 在上面的示例中，订阅者可能只对名称以“.jpg”或“.jpeg”结尾的blob感兴趣， + 此时`subject` 属性允许为该事件子集构建简单有效的字符串后缀过滤器。 + +- 约束条件: + - 可选的 + - 若有必须是非空字符串 +- 示例: + - 订阅者可能对在blob在blob存储容器中创建的时候感兴趣并订阅。 + 在这个场景下，事件`source`标示出订阅的范围（存储容器），`type` 标识出 + blob 创建" 这个事件，`id` 唯一标识出事件示例，以区分已创建同名blob的事件， + 而新创建的blob的名字可以放在`subject`属性中： + - `source`: https://example.com/storage/tenant/container + - `subject`: mynewfile.jpg + +#### time + +- 类型: `Timestamp` +- 描述: 事件发生的时间戳。 + 如果无法确定发生的时间，则 CloudEvents 生产者可以将此属性设置为其他时间（例如当前时间）。 + 但是在这方面，同一`source`的所有生产者必须保持一致。 + 换句话说，要么它们都使用发生的实际时间，要么它们都使用相同的算法来确定所使用的值。 + +- 约束条件: + - 可选的 + - 若有则必须遵守 + [RFC 3339](https://tools.ietf.org/html/rfc3339) + +### 扩展上下文属性 + +CloudEvent 可以包含任意数量的具有不同名称的附加上下文属性，被称为"扩展属性"。 +扩展属性必须遵循相同的[命名约定](#属性命名约定)并使用与标准属性相同的 +[类型系统](#类型系统)。 +扩展属性在本规范中没有定义好的含义， +它们允许外部系统将元数据附加到事件，就像 HTTP 自定义头部一样。 + +扩展属性总是如标准属性一样，根据绑定规则进行序列化。 +然而，该规范不阻止扩展将事件属性值复制到消息的其他部分， +以便与也其它处理消息的非 CloudEvents 系统进行交互。 +如果复制的值与云事件序列化值不同，执行此操作的扩展规范应该指定接收者如何解释消息。 + +#### 定义扩展 + +在 +[CloudEvent-属性扩展](primer_CN.md#CloudEvent-属性扩展) +查阅有关扩展使用和定义等相关信息。 + +扩展的定义应该完全定义属性的方方面面——例如 它的名称、类型、语义含义和可能的值。 +新的扩展定义应该使用一个足够描述性的名称来减少与其他扩展的名称冲突的机会。 +特别是，扩展作者应该检查[扩展文件](documented-extensions.md)中 +已知的扩展集——不仅是可能的名称冲突，还有相同目的冲突的扩展。 + +许多协议为发送者提供了包含额外元数据的能力，例如作为 HTTP 头部。 +虽然没有强制要求 CloudEvents 接受者处理和传递它们， +但建议接受者通过某种机制进行处理，以明确它们是非 CloudEvents 的元数据。 + +下面是一个示例，说明了 CloudEvents 对附加属性的需求。 +在许多物联网和企业用例中，事件可用于跨多种类型事件执行操作的serverless应用程序中。 +为了支持这样的用例，事件生产者需要向“上下文属性”添加额外的身份属性， +事件消费者可以使用这些属性将这个事件与其他事件相关联。 +如果此类身份属性恰好是事件“数据”的一部分， +则事件生产者还会将身份属性添加到“上下文属性”中， +以便事件消费者可以轻松访问此信息，而无需解码和检查事件数据。 +此类身份属性还可用于帮助中间网关确定如何路由事件。 + +## 事件数据 + +正如[数据](#数据)所定义的那样，CloudEvents 可以包括有关事件的特定域的信息。 +这些信息将被封装在`data`中。 + +- 描述: 事件负载。 本规范对该信息的类型不作任何限制。 + 它被编码为一种媒体格式，这种格式由`datacontenttype` 属性(如 application/json)指定， + 并在存在这些相应属性时遵循`dataschema`格式。 + It is encoded into a media format + +- 约束条件: + - 可选的 + +# 大小限制 + +在很多情况下，CloudEvents 将通过一个或多个通用中间人进行转发， +每个中间人都可能对转发事件的大小施加限制。 +CloudEvents 也可能直接被路由到消费者，如嵌入式设备， +这些设备是受存储或内存限制的，对单个大型事件表现不佳。 + +事件的“大小”是它的线路大小，包括在线路上为事件传输的每一位： +协议帧元数据、事件元数据和事件数据，基于所选的事件格式和所选的协议绑定。 + +如果应用程序配置需要跨不同协议路由事件或重新编码事件， +应用程序能使用的效率最低的协议和编码，都修腰符合这些大小限制： + +- 中间人转发的事件大小必须为 64 KB 或更小。 +- 消费者应该能接受大小至少为 64 KB 的事件。 + +为了方便，上述规则将允许生产者安全地发布最大 64KB 的事件。 +这里的安全意味着生产者期望事件被所有中间人接受并合理地转发。 +它是在任何特定消费者的控制之下，无论消费者是否由于本地考虑而选择接受或拒绝该大小的事件。 + +通常，CloudEvents 发布者应该通过避免将大型数据项嵌入到事件而使用事件有效链接到此类数据项， +来保持事件紧凑。 +从访问控制的角度来看，这种方法对更广泛的事件分布式化有帮助， +因为通过解析链接访问与事件相关的细节能实现差异化访问控制和选择性披露， +而不是将敏感详细数据直接嵌入到事件中。 + +# 隐私与安全 + +互操作性是本规范背后的主要驱动力， +实现此目标需要一些信息明确可用，这可能导致信息的泄漏。 + +考虑以下事项以防止信息意外泄漏，尤其是在利用第三方平台和通信网络时： + +- 上下文属性 + + 敏感信息不应在上下文属性中携带。 + + CloudEvent 生产者、消费者和中间人可以自查并记录下上下文属性。 + +- 数据 + + 特定的[事件数据](#事件数据) 应该被加密以限制对受信任方的可见性。 + 用于这种加密的机制是生产者和消费者之间的协议，不在本规范的讨论范围内。 + +- 协议绑定 + 应该采用协议级别的安全性机制来确保 CloudEvents 完成可信和安全的交换。 + +# 示例 + +以下示例展示了一个序列化为 JSON 的 CloudEvent： + +```JSON +{ + "specversion" : "1.0", + "type" : "com.github.pull.create", + "source" : "https://github.com/cloudevents/spec/pull", + "subject" : "123", + "id" : "A234-1234-1234", + "time" : "2018-04-05T17:31:00Z", + "comexampleextension1" : "value", + "comexampleothervalue" : 5, + "datacontenttype" : "text/xml", + "data" : "" +} +``` From 4b2968442473567229c018c309004b17ad91df40 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:55:28 +0800 Subject: [PATCH 30/60] Delete spec_CN.md --- spec_CN.md | 478 ----------------------------------------------------- 1 file changed, 478 deletions(-) delete mode 100644 spec_CN.md diff --git a/spec_CN.md b/spec_CN.md deleted file mode 100644 index e27e009d3..000000000 --- a/spec_CN.md +++ /dev/null @@ -1,478 +0,0 @@ -# CloudEvents 核心规范- 1.0 版本 - -Declaration： This manual aims to provide a fast and brief introduction of CloudEvents -in Chinese for people who are new to CloudEvents. -Most of the content is translated from the original English version. -It is strongly recommended to read the English version if you find anything lost in translation. - -## 摘要 - -CloudEvents 是一个用于定义事件格式的供应商中立规范。 - -## 目录 - -- [概览](#概览) -- [符号和术语](#符号和术语) -- [上下文属性](#上下文属性) -- [事件数据](#事件数据) -- [大小限制](#大小限制) -- [隐私与安全](#隐私与安全) -- [示例](#示例) - -## 概览 - -事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 - -对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。 -它同样限制了那些用来帮助事件数据完成 跨环境传输的库(如SDKs)， -工具(如事件路由器)和基础设施(如事件追踪系统)的发展。 -总体来看，这种匮乏严重阻碍了事件数据的可移植性和生产力。 - -CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 - -事件格式指定如何使用某些编码格式序列化一个 CloudEvent。 -支持那些编码且兼容 CloudEvents 的实现必须遵守相应事件格式中指定的编码规则。 -所有实现都必须支持 [JSON 格式](json-format.md)。 - -有关规范背后的历史、开发和设计原理等更多信息， -请参阅 CloudEvents [入门文档](primer_CN.md)。 - -## 符号和术语 - -### 符号约定 - -本文档中的关键词 -"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 需要按照 -[RFC 2119](https://tools.ietf.org/html/rfc2119) 中的描述来理解。 - -为清楚起见， -当一个功能被标记为“OPTIONAL”时，这意味着消息的 -[生产者](#生产者)和[消费者](#消费者) 都可以自行选择是否支持该功能。 -换句话说，生产者可以在需要时在消息中包含该功能，消费者也可以在需要时选择支持该功能。 -不支持该功能的消费者将默默地忽略该部分消息。 -生产者需要做好消费者并没有启用该功能的准备。 -[中间人](#中间人) 应当转发OPTIONAL属性。 - -### 术语 - -本规范定义了下列术语 - -#### 发生 - -“发生”是指在软件系统运行期间对事实状态的捕获。 -这可能是由于系统发出了信号或系统观察到信号、状态更改、计时器超时 -或任何其他值得注意的活动而发生的。 -例如，设备可能会因为电池电量低或虚拟机即将执行计划的重启而进入警报状态。 - -#### 事件 - -“事件”是表示一条"发生"及其上下文的数据记录。 -事件从事件生产者（源）路由到对它感兴趣的事件消费者。 -事件中包含的信息帮助完成路由操作，但事件不会标识特定的路由目的地。 -事件将包含两种类型的信息：表示"发生"的 [事件数据](#事件数据) -和提供有关事件的环境信息的[上下文](#上下文) 元数据。 -一次"发生"可能导致多个事件的产生。 - -#### 生产者 - -“生产者”是一种特定的实例、进程或设备，它能够创建用来描述CloudEvent的数据结构。 - -#### 源 - -"源"是事件发生的上下文环境。在分布式系统中，它可能由多个生产者组成。 -如果一个源无法查看到CloudEvents，那么一定有有外部的生产者在代替源来生产CloudEvent。 - -#### 消费者 - -一个“消费者”会接收事件并根据事件采取一定的行为。 -它使用上下文环境和事件数据来执行一些逻辑，这可能会导致新事件的发生。 - -#### 中间人 - -一个“中间人”会接收包含事件的消息， -并将其转发给下一个接收者，但该接收者可能是另一个中间人或事件[消费者](#消费者)。 -中间人的典型任务就是根据[上下文](#上下文)环境中的信息将事件路由到接收者。 - -#### 上下文 - -上下文环境元数据被封装在[上下文-属性](#上下文-属性)中。 -工具和应用程序代码可以使用此信息来识别事件与系统方面或事件与其他事件的关系。 - -#### 数据 - -关于事件的特定域信息（即有效负载）。这可能包括有关事件的信息、有关已更改数据的详细信息等。 -有关更多信息，请参阅[事件数据](#事件数据)部分。 - -#### 事件格式 - -一个事件格式会指定如何将 CloudEvent 序列化为字节序列。 -独立事件格式（例如 [JSON 格式](json-format.md)）指定独立于任何协议或存储介质的序列化。 -协议绑定可以定义依赖于协议的格式。 - -#### 消息 - -事件通过消息从源传输到目标。 - -“结构化模式消息”是一种使用独立事件格式对事件进行完全编码并存储在消息体中的消息。 - -“二进制模式消息”会将事件数据存储在消息体中，并将事件属性作为消息元数据的一部分存储下来。 - -#### 协议 - -消息可以通过各种行业标准协议 -（例如 HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或平台/供应商 -专有协议（AWS Kinesis、Azure 事件网格）传输。 - -#### 协议绑定 - -协议绑定描述了如何通过给定协议发送和接收事件，特别是如何将事件映射到该协议的消息中去。 - -## 上下文属性 - -每个符合本规范的 CloudEvent 必须包括指定为 REQUIRED 的上下文属性， -可以包括一个或多个OPTIONAL上下文属性， -并且可以包括一个或多个扩展属性。 - -这些属性虽然描述了事件，但被设计为可以独立于事件数据进行序列化。 -这允许在不反序列化事件数据的情况下，在目的检查这些上下文属性。 - -### 属性命名约定 - -CloudEvents 规范定义了到各种协议和编码的映射，随附的 CloudEvents SDK 面向各种运行时和编程语言。 -其中一些将元数据元素区分大小写，而另一些则不区分， -并且单个 CloudEvent 可能通过涉及到协议、编码和运行时混合的多个跃点进行路由。 -因此，本规范限制了所有属性的可用字符集，以防止区分大小写问题或与通用语言中标识符的合法字符集冲突问题。 - -CloudEvents 属性名称必须由来自 ASCII 字符集的小写字母（“a”到“z”）或数字（“0”到“9”）组成。 -属性名称应该是描述性的和简洁的，并且长度不应超过 20 个字符。 - -### 类型系统 - -以下抽象数据类型可用于属性。 -这些类型中的每一种都可以由不同的事件格式和协议元数据字段以不同的方式表示。 -本规范为所有实现必须支持的每种类型定义了规范的字符串编码。 - -- `Boolean` - “true”或“false”的布尔值。 - - 字符串编码：区分大小写的`true` 或 `false`值。 -- `Integer` -范围在 -2,147,483,648 到 +2,147,483,647 （包含）之间的整数。 - 这是有符号 32 位二进制补码编码的范围。 - 事件格式不必使用此编码，但它们必须使用在此范围内的`Integer` 值。 - - 字符串编码: 符合 - [RFC 7159, 第 6 节](https://tools.ietf.org/html/rfc7159#section-6) - JSON 数字的整数部分 -- `String` - 允许的 Unicode 字符序列。 不允许使用以下字符： - - 范围 U+0000-U+001F 和 U+007F-U+009F（包含首尾）中的“控制字符”， - 因为大多数没有商定的含义，还有一些，例如 U+000A（换行符）， 在如 HTTP 头部之类的上下文中不可用。 - -[被 Unicode 标识为非字符的](http://www.unicode.org/faq/private_use.html#noncharacters) - 代码点。 - - 被 Unicode 标识为代理项的代码点, 范围 U+D800-U+DBFF 和 U+DC00-U+DFFF（包含首尾） - , 除非被合理的用作代理对. 因此（在 JSON 符号中） - “\uDEAD”是无效的，因为它是一个未配对的代理，而“\uD800\uDEAD”是合法的。 -- `Binary` - 字节序列. - - 字符串编码: 基于 - [RFC4648](https://tools.ietf.org/html/rfc4648) 的Base64 编码。 -- `URI` - 绝对统一资源标识符。 - - 字符串编码: - [RFC 3986 第 4.3 节](https://tools.ietf.org/html/rfc3986#section-4.3) - 中定义的 `Absolute URI` 。 -- `URI-reference` - 统一资源标识符引用。 - - 字符串编码: - [RFC 3986 第 4.1 节](https://tools.ietf.org/html/rfc3986#section-4.1) - 中定义的`URI-reference` 。 -- `Timestamp` - 使用公历的日期和时间表达式。 - - 字符串编码: [RFC 3339](https://tools.ietf.org/html/rfc3339) 。 - -所有上下文属性值必须是上面列出的类型之一。 -属性值可以表示为原生类型或规范字符串。 - -当强类型编程语言表示 CloudEvent 或任何扩展时， -必须能够在规范字符串编码与对应抽象类型的运行时/编程语言类型之间进行转换。 - -例如，在给定的实现中，`time` 属性可能由编程语言的本地时间类型表示， -但它必须是可设置提供 RFC3339 字符串的， -并且当映射到 HTTP 消息头时，它必须可转换为 RFC3339 字符串。 - -CloudEvents 协议绑定或事件格式实现同样必须能够 -在规范字符串编码与协议元数据字段中的对应数据类型之间进行转换。 - -`Timestamp` 类型的属性值确实可能以字符串形式路由通过多个跃点， -并且仅在生产者和最终消费者处实现为本地运行时/语言类型。 -`Timestamp` 类型也可以作为本机协议类型路由， -并且可以在生产者和消费者端映射到/从各自的语言/运行时类型，但永远不会转为字符串格式。 - -序列化机制的选择将决定上下文属性和事件数据将如何序列化。 -例如，在 JSON 序列化的情况下，上下文属性和事件数据可能都出现在同一个 JSON 对象中。 - -### 必要属性 - -下列属性必须自所有的 CloudEvents 中展示： - -#### id - -- 类型: `String` -- 描述: 标识一个事件。 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 - 如果重复的事件被重新发送（例如由于网络错误），它可能具有相同的 `id`。 - Consumers MAY assume that - 消费者可以假设具有相同`source` 和 `id`的事件是重复的。 -- 示例: - - 一个由生产者维护的事件计数器 - - 一个 UUID -- 约束条件: - - 必要的 - - 必须是非空字符串 - - 在生产者的范围内必须是唯一的 - -#### source - -- 类型: `URI-reference` -- 描述: 标识事件发生的上下文背景。 这通常包括诸如事件源类型、发布事件的组织 - 或产生事件的过程等信息。URI 中编码的数据背后的确切语法和语义由事件生产者定义。 - - 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 - - 应用程序可以为每个不同的生产者分配一个唯一的`source`， - 这使得生成唯一 ID 变得容易，因为没有其他生产者将拥有相同的来源。 - 应用程序可以使用 UUIDs、URNs、DNS权威机构或特定于应用程序的方案来创建唯一的`source` 标识符。 - - 一个来源可以包括多个生产者。 - 在这种情况下，生产者必须协作以确保每个不同事件的 `source` + `id`都是唯一的。 - -- 约束条件: - - 必要的 - - 必须是非空 URI-reference - - 推荐使用 绝对 URI -- 示例 - - 具有 DNS 权限的 Internet 范围唯一 URI： - - https://github.com/cloudevents - - mailto:cncf-wg-serverless@lists.cncf.io - - 具有 UUID 的通用唯一 URN： - - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 - - 应用程序专有的标识符 - - /cloudevents/spec/pull/123 - - /sensors/tn-1234567/alerts - - 1-555-123-4567 - -#### specversion - -- 类型: `String` -- 描述: 事件使用的 CloudEvents 规范的版本。 - 这让解释上下文环境更容易。 - 当引用这个版本的规范时，兼容的事件生产者必须使用 `1.0` 的值。 -- 约束条件: - - 必要的 - - 必须是非空字符串 - -#### type - -- 类型: `String` -- 描述: 该属性包含一个值，描述与原始事件相关的事件类型。 - 该属性通常用于路由、可观察性、策略实施等。其格式是生产者定义的，可能包括诸如 `type`版本之类的信息 - -从 - [入门文档-属性版本控制](primer_CN.md#属性版本控制) 中获得更多信息 - -- 约束条件: - - 必要的 - - 必须是非空字符串 - - 应该以反向 DNS 名称作为前缀。该前缀域表明了定义此事件类型语义的组织。 -- 示例 - - com.github.pull.create - - com.example.object.delete.v2 - -### 可选属性 - -下列属性在 CloudEvents 中是可选的. 在 -[符号约定](#notational-conventions) 中查看更多 OPTIONAL 定义的信息。 - -#### datacontenttype - -- 类型: `String` [RFC 2046](https://tools.ietf.org/html/rfc2046) -- 描述: `data`值的内容类型。 此属性使`data`能够承载任何类型的内容， - 因此格式和编码可能与所选事件格式的不同。 - 例如，使用 [JSON envelope](./json-format.md#3-envelope) - 格式呈现的事件可能在数据中携带 XML 的payload，这个属性可以用来通知消费者 - 设置"application/xml"。 - 关于`data`内容如何提供不同的`datacontenttype`的值的规则在事件格式规范中定义。 - 例如，JSON 事件格式定义了 [3.1 节](./json-format.md#31-handling-of-data)中的关系。 - 对于某些二进制模式协议绑定， - 此字段直接能映射到相应协议的内容类型的元数据属性上。 - 二进制模式和内容类型元数据映射的规范规则可以在各自的协议中找到。 - - 在某些事件格式中，可以省略 `datacontenttype` 属性。 - 例如，如果 JSON 格式的事件没有 `datacontenttype` 属性， - 则表示该`data`是符合“application/json”媒体类型的 JSON 值。 - 换句话说：一个没有 `datacontenttype` 的 JSON 格式的事件完全等同于 - 一个带有 `datacontenttype="application/json"`的事件。 - - 当将没有 `datacontenttype` 属性的事件消息转换为不同的格式或协议绑定时， - 目标 `datacontenttype` 应该显式设置为事件源的隐含或默认的 `datacontenttype`。 - -- 约束条件: - - 可选的 - - 若有则必须遵守 - [RFC 2046](https://tools.ietf.org/html/rfc2046) 制定的格式 -- 媒体类型示例 - [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml) - -#### dataschema - -- 类型: `URI` -- 描述: 标识 `data` 遵守的规范。 对模式的不兼容的更改应该由不同的 URI 体现。 在 - [入门文档-属性版本控制](primer_CN.md#属性版本控制) - 中查看更多信息。 -- 约束条件: - - 可选的 - - 若有必须是非空的 URI - -#### subject - -- 类型: `String` -- 描述: 这个属性描述了事件生产者 (由`source`标识) 上下文环境中的主题信息。 - 在发布-订阅场景中，订阅者通常会订阅`source`发出的事件， - 但如果`source` 的上下文环境具有内部子结构， - 则单独的`source`标识符可能不足以作为任何指定事件的限定符。 - - 在上下文元数据中识别事件的主题（与仅在数据负载中相反） - 对于中间件无法解释`data` 内容的通用订阅过滤场景特别有用。 - 在上面的示例中，订阅者可能只对名称以“.jpg”或“.jpeg”结尾的blob感兴趣， - 此时`subject` 属性允许为该事件子集构建简单有效的字符串后缀过滤器。 - -- 约束条件: - - 可选的 - - 若有必须是非空字符串 -- 示例: - - 订阅者可能对在blob在blob存储容器中创建的时候感兴趣并订阅。 - 在这个场景下，事件`source`标示出订阅的范围（存储容器），`type` 标识出 - blob 创建" 这个事件，`id` 唯一标识出事件示例，以区分已创建同名blob的事件， - 而新创建的blob的名字可以放在`subject`属性中： - - `source`: https://example.com/storage/tenant/container - - `subject`: mynewfile.jpg - -#### time - -- 类型: `Timestamp` -- 描述: 事件发生的时间戳。 - 如果无法确定发生的时间，则 CloudEvents 生产者可以将此属性设置为其他时间（例如当前时间）。 - 但是在这方面，同一`source`的所有生产者必须保持一致。 - 换句话说，要么它们都使用发生的实际时间，要么它们都使用相同的算法来确定所使用的值。 - -- 约束条件: - - 可选的 - - 若有则必须遵守 - [RFC 3339](https://tools.ietf.org/html/rfc3339) - -### 扩展上下文属性 - -CloudEvent 可以包含任意数量的具有不同名称的附加上下文属性，被称为"扩展属性"。 -扩展属性必须遵循相同的[命名约定](#属性命名约定)并使用与标准属性相同的 -[类型系统](#类型系统)。 -扩展属性在本规范中没有定义好的含义， -它们允许外部系统将元数据附加到事件，就像 HTTP 自定义头部一样。 - -扩展属性总是如标准属性一样，根据绑定规则进行序列化。 -然而，该规范不阻止扩展将事件属性值复制到消息的其他部分， -以便与也其它处理消息的非 CloudEvents 系统进行交互。 -如果复制的值与云事件序列化值不同，执行此操作的扩展规范应该指定接收者如何解释消息。 - -#### 定义扩展 - -在 -[CloudEvent-属性扩展](primer_CN.md#CloudEvent-属性扩展) -查阅有关扩展使用和定义等相关信息。 - -扩展的定义应该完全定义属性的方方面面——例如 它的名称、类型、语义含义和可能的值。 -新的扩展定义应该使用一个足够描述性的名称来减少与其他扩展的名称冲突的机会。 -特别是，扩展作者应该检查[扩展文件](documented-extensions.md)中 -已知的扩展集——不仅是可能的名称冲突，还有相同目的冲突的扩展。 - -许多协议为发送者提供了包含额外元数据的能力，例如作为 HTTP 头部。 -虽然没有强制要求 CloudEvents 接受者处理和传递它们， -但建议接受者通过某种机制进行处理，以明确它们是非 CloudEvents 的元数据。 - -下面是一个示例，说明了 CloudEvents 对附加属性的需求。 -在许多物联网和企业用例中，事件可用于跨多种类型事件执行操作的serverless应用程序中。 -为了支持这样的用例，事件生产者需要向“上下文属性”添加额外的身份属性， -事件消费者可以使用这些属性将这个事件与其他事件相关联。 -如果此类身份属性恰好是事件“数据”的一部分， -则事件生产者还会将身份属性添加到“上下文属性”中， -以便事件消费者可以轻松访问此信息，而无需解码和检查事件数据。 -此类身份属性还可用于帮助中间网关确定如何路由事件。 - -## 事件数据 - -正如[数据](#数据)所定义的那样，CloudEvents 可以包括有关事件的特定域的信息。 -这些信息将被封装在`data`中。 - -- 描述: 事件负载。 本规范对该信息的类型不作任何限制。 - 它被编码为一种媒体格式，这种格式由`datacontenttype` 属性(如 application/json)指定， - 并在存在这些相应属性时遵循`dataschema`格式。 - It is encoded into a media format - -- 约束条件: - - 可选的 - -# 大小限制 - -在很多情况下，CloudEvents 将通过一个或多个通用中间人进行转发， -每个中间人都可能对转发事件的大小施加限制。 -CloudEvents 也可能直接被路由到消费者，如嵌入式设备， -这些设备是受存储或内存限制的，对单个大型事件表现不佳。 - -事件的“大小”是它的线路大小，包括在线路上为事件传输的每一位： -协议帧元数据、事件元数据和事件数据，基于所选的事件格式和所选的协议绑定。 - -如果应用程序配置需要跨不同协议路由事件或重新编码事件， -应用程序能使用的效率最低的协议和编码，都修腰符合这些大小限制： - -- 中间人转发的事件大小必须为 64 KB 或更小。 -- 消费者应该能接受大小至少为 64 KB 的事件。 - -为了方便，上述规则将允许生产者安全地发布最大 64KB 的事件。 -这里的安全意味着生产者期望事件被所有中间人接受并合理地转发。 -它是在任何特定消费者的控制之下，无论消费者是否由于本地考虑而选择接受或拒绝该大小的事件。 - -通常，CloudEvents 发布者应该通过避免将大型数据项嵌入到事件而使用事件有效链接到此类数据项， -来保持事件紧凑。 -从访问控制的角度来看，这种方法对更广泛的事件分布式化有帮助， -因为通过解析链接访问与事件相关的细节能实现差异化访问控制和选择性披露， -而不是将敏感详细数据直接嵌入到事件中。 - -# 隐私与安全 - -互操作性是本规范背后的主要驱动力， -实现此目标需要一些信息明确可用，这可能导致信息的泄漏。 - -考虑以下事项以防止信息意外泄漏，尤其是在利用第三方平台和通信网络时： - -- 上下文属性 - - 敏感信息不应在上下文属性中携带。 - - CloudEvent 生产者、消费者和中间人可以自查并记录下上下文属性。 - -- 数据 - - 特定的[事件数据](#事件数据) 应该被加密以限制对受信任方的可见性。 - 用于这种加密的机制是生产者和消费者之间的协议，不在本规范的讨论范围内。 - -- 协议绑定 - 应该采用协议级别的安全性机制来确保 CloudEvents 完成可信和安全的交换。 - -# 示例 - -以下示例展示了一个序列化为 JSON 的 CloudEvent： - -```JSON -{ - "specversion" : "1.0", - "type" : "com.github.pull.create", - "source" : "https://github.com/cloudevents/spec/pull", - "subject" : "123", - "id" : "A234-1234-1234", - "time" : "2018-04-05T17:31:00Z", - "comexampleextension1" : "value", - "comexampleothervalue" : 5, - "datacontenttype" : "text/xml", - "data" : "" -} -``` From 79ae60a1e37977ff2ddef04f1367ad448642e639 Mon Sep 17 00:00:00 2001 From: JieDing Date: Sat, 6 Nov 2021 20:17:35 +0800 Subject: [PATCH 31/60] Update README.md CloudEvents Chinese manual aims to provide a fast and brief introduction of CloudEvents in Chinese for people who are new to CloudEvents. Signed-off-by: JieDing --- README.md | 148 +++++++++++++++++++++++++----------------------------- 1 file changed, 69 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index c26f0b7df..5396058f1 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,37 @@ -# CloudEvents +# CloudEvents Chinese Manual ![CloudEvents logo](https://github.com/cncf/artwork/blob/master/projects/cloudevents/horizontal/color/cloudevents-horizontal-color.png) -Events are everywhere. However, event producers tend to describe events -differently. +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. -The lack of a common way of describing events means developers must constantly -re-learn how to consume events. This also limits the potential for libraries, -tooling and infrastructure to aide the delivery of event data across -environments, like SDKs, event routers or tracing systems. The portability and -productivity we can achieve from event data is hindered overall. +声明：这份中文手册旨在帮助初次接触CloudEvents的人快速建立起CloudEvents的相关认知。 +手册中的大部分内容翻译自英文版的CloudEvents标准，当你遇到令你困惑的内容时，请对照英文版理解。 -CloudEvents is a specification for describing event data in common formats to -provide interoperability across services, platforms and systems. +事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 -CloudEvents has received a large amount of industry interest, ranging from major -cloud providers to popular SaaS companies. CloudEvents is hosted by the -[Cloud Native Computing Foundation](https://cncf.io) (CNCF) and was approved as -a Cloud Native sandbox level project on -[May 15, 2018](https://docs.google.com/presentation/d/1KNSv70fyTfSqUerCnccV7eEC_ynhLsm9A_kjnlmU_t0/edit#slide=id.g37acf52904_1_41). +对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。它同样限制了那些用来帮助事件数据完成 +跨环境传输的库(如SDKs)，工具(如事件路由器)和基础设施(如事件追踪系统)的发展。总体来看，这种匮乏严重阻碍了事件数据的 +可移植性和生产力。 -## CloudEvents Documents +CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 -The following documents are available: +CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvents被[云原生计算基金会](https://cncf.io) (CNCF)持有， +在[2018/05/15](https://docs.google.com/presentation/d/1KNSv70fyTfSqUerCnccV7eEC_ynhLsm9A_kjnlmU_t0/edit#slide=id.g37acf52904_1_41) +被选为云原生沙盒级项目。 -| | Latest Release | Working Draft | +## CloudEvents 文件 + +现有文件如下: + +| | 最新版本 | 工作草稿 | | :---------------------------- | :----------------------------------------------------------------------------: | :---------------------------------------------------------------------------------: | -| **Core Specification:** | +| **核心标准:** | | CloudEvents | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/spec.md) | [master](https://github.com/cloudevents/spec/blob/master/spec.md) | | | -| **Optional Specifications:** | +| **可选标准:** | | AMQP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/amqp-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-protocol-binding.md) | | AVRO Event Format | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/avro-format.md) | [master](https://github.com/cloudevents/spec/blob/master/avro-format.md) | | HTTP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/http-protocol-binding.md) | @@ -39,26 +41,22 @@ The following documents are available: | NATS Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/nats-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/nats-protocol-binding.md) | | Web hook | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md) | [master](https://github.com/cloudevents/spec/blob/master/http-webhook.md) | | | -| **Additional Documentation:** | +| **附加文件:** | | CloudEvents Adapters | - | [master](https://github.com/cloudevents/spec/blob/master/adapters.md) | | CloudEvents SDK Requirements | - | [master](https://github.com/cloudevents/spec/blob/master/SDK.md) | | Documented Extensions | - | [master](https://github.com/cloudevents/spec/blob/master/documented-extensions.md) | | Primer | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/primer.md) | [master](https://github.com/cloudevents/spec/blob/master/primer.md) | | Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | -If you are new to CloudEvents, it is recommended that you start by reading the -[Primer](primer.md) for an overview of the specification's goals and design -decisions, and then move on to the [core specification](spec.md). +对于初次接触CloudEvents的同学，建议通过阅读[入门文档](primer.md)增加对CloudEvents规范的目标和设计理念 +的总体理解，然后再继续阅读[核心规范](spec.md)。 -Since not all event producers generate CloudEvents by default, there is -documentation describing the recommended process for adapting some popular -events into CloudEvents, see -[CloudEvents Adapters](https://github.com/cloudevents/spec/blob/master/adapters.md). +由于并非所有事件生产者都默认生产符合CloudEvents规范的事件，因此可以用[CloudEvents适配器](https://github.com/cloudevents/spec/blob/master/adapters.md) +来将现有的事件与CloudEvents做适配。 ## SDKs -In addition to the documentation mentioned above, there are also an -[SDK proposal](SDK.md) and a set of SDKs being developed: +除了上述文档，我们还提供了[SDK 提议](SDK.md)以及一些编程语言的SDK： - [CSharp](https://github.com/cloudevents/sdk-csharp) - [Go](https://github.com/cloudevents/sdk-go) @@ -66,79 +64,71 @@ In addition to the documentation mentioned above, there are also an - [Javascript](https://github.com/cloudevents/sdk-javascript) - [Python](https://github.com/cloudevents/sdk-python) -## Community - -Learn more about the people and organizations who are creating a dynamic cloud -native ecosystem by making our systems interoperable with CloudEvents. - -- [Contributors](community/contributors.md): people and organizations who helped - us get started or are actively working on the CloudEvents specification. -- Coming soon: [demos & open source](community/README.md) -- if you have - something to share about your use of CloudEvents, please submit a PR! +## 社区 -## Process +在社区里，你可以了解到更多致力于搭建一个动态、云原生的生态系统的成员和组织。 +他们不断尝试提升现有系统和CloudEvents间的互操作性和兼容性。 -The CloudEvents project is working to formalize the [specification](spec.md) -based on [design goals](primer.md#design-goals) which focus on interoperability -between systems which generate and respond to events. +- [贡献者](community/contributors.md): + 是指那些帮助我们制定规范或是积极活跃在CloudEvents规范相关工作的成员和组织。 +- 即将推出: [demos & open source](community/README.md) -- + 如果你希望向我们分享关于你对CloudEvents的使用，请通过提交PR让我们看到。 -In order to achieve these goals, the project must describe: +## 步骤 -- Common attributes of an _event_ that facilitate interoperability -- One or more common architectures that are in active use today or planned to be - built by its members -- How events are transported from producer to consumer via at least one protocol -- Identify and resolve whatever else is needed for interoperability +CloudEvents项目 [旨在](primer.md#design-goals)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 +的[标准](spec.md)。 -## Communications +为了完成这个目标，这个项目必须描述： -The mailing list for e-mail communications: +- 一系列能够提升互操作性的用来描述事件的属性 +- 一个或多个通用架构，这些架构必须是当下活跃的或是正在计划被完成的 +- 事件是如何在一种或多种协议下从生产者传输到消费者的 +- 识别并解决任何能提升互操作性的问题 +## 联系方式 -- Send emails to: [cncf-cloudevents](mailto:cncf-cloudevents@lists.cncf.io) -- To subscribe see: https://lists.cncf.io/g/cncf-cloudevents -- Archives are at: https://lists.cncf.io/g/cncf-cloudevents/topics +邮件联系方式如下: -And a #cloudevents Slack channel under -[CNCF's Slack workspace](https://slack.cncf.io/). +- 发送EMail至: [cncf-cloudevents](mailto:cncf-cloudevents@lists.cncf.io) +- 订阅地址: https://lists.cncf.io/g/cncf-cloudevents +- 存档地址: https://lists.cncf.io/g/cncf-cloudevents/topics -## Meeting Time +## 会议时间 -See the [CNCF public events calendar](https://www.cncf.io/community/calendar/). -This specification is being developed by the -[CNCF Serverless Working Group](https://github.com/cncf/wg-serverless). This -working group meets every Thursday at 9AM PT (USA Pacific): +会议日期请查看 [CNCF 公开活动日历](https://www.cncf.io/community/calendar/). +CloudEvents规范由 +[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless)开发完成。 +这个工作组每周四的上午9点(美国-太平洋时间)通过Zoom开展视频会议。 +通过 PC, Mac, Linux, iOS or Android来参加活动: https://zoom.us/my/cncfserverlesswg -Join from PC, Mac, Linux, iOS or Android: https://zoom.us/my/cncfserverlesswg - -Or iPhone one-tap : +或者通过 iPhone one-tap : US: +16465588656,,3361029682# or +16699006833,,3361029682# -Or Telephone: +或者电话接入: Dial: US: +1 646 558 8656 (US Toll) or +1 669 900 6833 (US Toll) or +1 855 880 1246 (Toll Free) or +1 877 369 0926 (Toll Free) -Meeting ID: 336 102 9682 +会议 ID: 336 102 9682 -International numbers available: +国际号码接入: https://zoom.us/zoomconference?m=QpOqQYfTzY_Gbj9_8jPtsplp1pnVUKDr -NOTE: Please use \*6 to mute/un-mute your phone during the call. - -World Time Zone Converter: +世界时区转化器: http://www.thetimezoneconverter.com/?t=9:00%20am&tz=San%20Francisco& -## Meeting Minutes +## 会议记录 + +历史会议记录在 +[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) +查看。 -The minutes from our calls are available -[here](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#). +历史会议录像在 +[这里](https://www.youtube.com/playlist?list=PLj6h78yzYM2Ph7YoBIgsZNW_RGJvNlFOt) +查看。 -Recording from our calls are available -[here](https://www.youtube.com/playlist?list=PLj6h78yzYM2Ph7YoBIgsZNW_RGJvNlFOt). +工作组会定期举办与主流会议一致的线下会议。查看[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) +了解更多未来计划。 -Periodically, the group may have in-person meetings that coincide with a major -conference. Please see the -[meeting minutes](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) -for any future plans. From 772e4f806585fe3c52e56151731922b8c7521fb2 Mon Sep 17 00:00:00 2001 From: JieDing Date: Sat, 6 Nov 2021 21:16:45 +0800 Subject: [PATCH 32/60] Update primer.md Signed-off-by: JieDing --- primer.md | 49 +++++++++++++++++++++++-------------------------- 1 file changed, 23 insertions(+), 26 deletions(-) diff --git a/primer.md b/primer.md index 367262195..5556eb330 100644 --- a/primer.md +++ b/primer.md @@ -1,35 +1,32 @@ -# CloudEvents Primer - Version 1.0 - -## Abstract - -This non-normative document provides an overview of the CloudEvents -specification. It is meant to complement the CloudEvent specification to provide -additional background and insight into the history and design decisions made -during the development of the specification. This allows the specification -itself to focus on the normative technical details. - -## Table of Contents - -- [History](#history) -- [CloudEvents Concepts](#cloudevents-concepts) -- [Design Goals](#design-goals) -- [Architecture](#architecture) -- [Versioning of Attributes](#versioning-of-attributes) -- [CloudEvent Attributes](#cloudevent-attributes) -- [CloudEvent Attribute Extensions](#cloudevent-attribute-extensions) -- [Creating CloudEvents](#creating-cloudevents) -- [Qualifying Protocols and Encodings](#qualifying-protocols-and-encodings) -- [Proprietary Protocols and Encodings](#proprietary-protocols-and-encodings) +# CloudEvents 入门文档 - 1.0 版本 + +## 摘要 + +这份非技术规范文档用来为你提供关于CloudEvents规范的总体概览。它补充了CloudEvents规范的相关背景以及在制定 +本规范时的历史和设计理念。这样，CloudEvents规范就只需要关注Events规范的技术细节，而不用过多地关心 +背景相关内容。 + +## 目录 + +- [历史](#history) +- [CloudEvents 概念](#cloudevents-concepts) +- [设计目标](#design-goals) +- [架构](#architecture) +- [属性版本](#versioning-of-attributes) +- [CloudEvent 属性](#cloudevent-attributes) +- [CloudEvent 属性扩展](#cloudevent-attribute-extensions) +- [生产 CloudEvents](#creating-cloudevents) +- [Qualifying 协议和编码](#qualifying-protocols-and-encodings) +- [Proprietary 协议和编码](#proprietary-protocols-and-encodings) - [Prior Art](#prior-art) - [Roles](#roles) - [Value Proposition](#value-proposition) - [Existing Event Formats](#existing-event-formats) -## History +## 历史 -The [CNCF Serverless Working group](https://github.com/cncf/wg-serverless) was -originally created by the CNCF's -[Technical Oversight Committee](https://github.com/cncf/toc) to investigate +[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless)是由 CNCF的 +[技术监管委员会](https://github.com/cncf/toc) to investigate Serverless Technology and to recommend some possible next steps for some CNCF related activities in this space. One of the recommendations was to investigate the creation of a common event format to aid in the portability of functions From 1af1e307b70927b2793949cda972207241f7e316 Mon Sep 17 00:00:00 2001 From: JieDing Date: Sun, 7 Nov 2021 00:05:10 +0800 Subject: [PATCH 33/60] update contents Signed-off-by: JieDing --- README.md | 5 +- primer.md | 141 ++++++++++++++++++++++-------------------------------- 2 files changed, 57 insertions(+), 89 deletions(-) diff --git a/README.md b/README.md index 5396058f1..035a7b928 100644 --- a/README.md +++ b/README.md @@ -7,9 +7,6 @@ in Chinese for people who are new to CloudEvents. Most of the content is translated from the original English version. It is strongly recommended to read the English version if you find anything lost in translation. -声明：这份中文手册旨在帮助初次接触CloudEvents的人快速建立起CloudEvents的相关认知。 -手册中的大部分内容翻译自英文版的CloudEvents标准，当你遇到令你困惑的内容时，请对照英文版理解。 - 事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。它同样限制了那些用来帮助事件数据完成 @@ -20,7 +17,7 @@ CloudEvents是一个以通用格式来描述事件数据的标准。它提供了 CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvents被[云原生计算基金会](https://cncf.io) (CNCF)持有， 在[2018/05/15](https://docs.google.com/presentation/d/1KNSv70fyTfSqUerCnccV7eEC_ynhLsm9A_kjnlmU_t0/edit#slide=id.g37acf52904_1_41) -被选为云原生沙盒级项目。 +被选为云原生沙箱级项目。 ## CloudEvents 文件 diff --git a/primer.md b/primer.md index 5556eb330..85c4b51d6 100644 --- a/primer.md +++ b/primer.md @@ -26,103 +26,74 @@ ## 历史 [CNCF Serverless 工作组](https://github.com/cncf/wg-serverless)是由 CNCF的 -[技术监管委员会](https://github.com/cncf/toc) to investigate -Serverless Technology and to recommend some possible next steps for some CNCF -related activities in this space. One of the recommendations was to investigate -the creation of a common event format to aid in the portability of functions -between Cloud providers and the interoperability of processing of event streams. -As a result, the CloudEvents specification was created. +[技术监管委员会](https://github.com/cncf/toc) 成立，用于研究 +Serverless相关技术并为CNCF推荐相关领域的未来发展计划。其中一项建议就是研究创建一种通用事件格式， +用于提升不同云厂商间函数的可移植性和事件流处理的互操作性。就此，CloudEvents应运而生。 -While initially the work on CloudEvents was done as part of the Serverless -Working group, once the specification reached its v0.1 milestone, the TOC -approved the CloudEvents work as a new stand-alone CNCF sandbox project. +尽管CloudEvents起初是作为Serverless工作组的项目进行的，但随着CloudEvents规范完成它v0.1版本的里程碑， +技术监管委员会批准了CloudEvents工作作为一个新的独立的CNCF沙箱级项目。 -## CloudEvents Concepts +## CloudEvents 概念 -An [event](spec.md#event) includes context and data about an -[occurrence](spec.md#occurrence). Each _occurrence_ is uniquely identified by -the data of the _event_. +一个[事件](spec.md#event)包含了[事件发生](spec.md#occurrence)的上下文和相关数据。 +事件的相关数据可以用来唯一标识一件事件的发生。 -_Events_ represent facts and therefore do not include a destination, whereas -messages convey intent, transporting data from a source to a given destination. +事件代表了已发生的事实，因此它并不包含任何目的地相关信息，但消息能够传达事件内容，从而将事件数据 +从源头传输到指定的目的地。 -### Eventing +### 事件使用 -Events are commonly used in server-side code to connect disparate systems where -the change of state in one system causes code to execute in another. For -example, a source may generate an event when it receives an external signal -(e.g. HTTP or RPC) or observes a changing value (e.g. an IoT sensor or period of -inactivity). +事件通常在服务器端代码中使用来连接不同的系统，其中一个系统中的状态变化会导致代码在另一个系统中执行。 +比如，一个事件源，可能会在收到某个外部信号(如HTTP或RPC)或观察到状态变化(如IoT传感器数据变化或不活跃) +时，生产一个事件。 -To illustrate how a system uses CloudEvents, the simplified diagram below shows -how an event from a [source](spec.md#source) triggers an action. +为了更好地解释一个系统如何使用CloudEvents，下图展示了一个从事件源生产的事件是如何触发一个行为的。 ![alt text](source-event-action.png "A box representing the source with arrow pointing to a box representing the action. The arrow is annotated with 'e' for event and 'protocol'.") -The source generates a message where the event is encapsulated in a protocol. -The event arrives to a destination, triggering an action which is provided with -the event data. - -A _source_ is a specific instance of a source-type which allows for staging and -test instances. Open source software of a specific _source-type_ may be deployed -by multiple companies or providers. - -Events can be delivered through various industry standard protocols (e.g. HTTP, -AMQP, MQTT, SMTP), open-source protocols (e.g. Kafka, NATS), or platform/vendor -specific protocols (AWS Kinesis, Azure Event Grid). - -An action processes an event defining a behavior or effect which was triggered -by a specific _occurrence_ from a specific _source_. While outside of the scope -of the specification, the purpose of generating an _event_ is typically to allow -other systems to easily react to changes in a source that they do not control. -The _source_ and action are typically built by different developers. Often the -_source_ is a managed service and the _action_ is custom code in a serverless -Function (such as AWS Lambda or Google Cloud Functions). - -## Design Goals - -CloudEvents are typically used in a distributed system to allow for services to -be loosely coupled during development, deployed independently, and later can be -connected to create new applications. - -The goal of the CloudEvents specification is to define interoperability of event -systems that allow services to produce or consume events, where the producer and -consumer can be developed and deployed independently. A producer can generate -events before a consumer is listening, and a consumer can express an interest in -an event or class of events that is not yet being produced. Note that the -specifications produced by this effort are focused on interoperability of the -event format and how it appears while being sent on various protocols, such as -HTTP. The specifications will not focus on the processing model of either the -event producer or event consumer. - -CloudEvents, at its core, defines a set of metadata, called attributes, about -the event being transferred between systems, and how those pieces of metadata -should appear in that message. This metadata is meant to be the minimal set of -information needed to route the request to the proper component and to -facilitate proper processing of the event by that component. So, while this -might mean that some of the application data of the event itself might be -duplicated as part of the CloudEvent's set of attributes, this is to be done -solely for the purpose of proper delivery, and processing, of the message. Data -that is not intended for that purpose should instead be placed within the event -(`data`) itself. - -Additionally, it is assumed that the metadata needed by the protocol layer to -deliver the message to the target system is handled entirely by the protocol -and therefore is not included within the CloudEvents attributes. See the -[Non-Goals](#non-goals) section for more details. - -Along with the definition of these attributes, there will also be specifications -of how to serialize the event in different formats (e.g. JSON) and protocols -(e.g. HTTP, AMQP, Kafka). - -Batching of multiple events into a single API call is natively supported by some -protocols. To aid interoperability, it is left up to the protocols if and how -batching is implemented. Details may be found in the protocol binding or in the -protocol specification. A batch of CloudEvents carries no semantic meaning and -is not ordered. An [Intermediary](spec.md#intermediary) can add or remove -batching as well as assign events to different batches. +事件源生产了一条封装了基于某种协议的事件数据的消息。 +当载有事件的消息到达目的地时，会触发一个使用了事件数据的行为函数。 + +一个事件源是那些允许暂存和测试实例的源类型的特定实例。 +某个特定源类型的开源软件可能由多个公司或提供商部署。 + +事件可以通过各种行业标准协议（如HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或 +平台/供应商专有协议（AWS Kinesis、Azure Event Grid）传输。 + +一个操作函数能够处理那些定义了行为或影响的事件，这些行为和效果由来自特定来源的特定事件触发而来。 +虽然超出了规范的范围，但生成事件的目的通常是让其他系统能够轻松地对它们无法控制的源中的更改做出反应。 +源和操作通常由不同的开发人员构建。 +通常，源是托管服务，而操作是serverless函数（如 AWS Lambda 或 Google Cloud Functions）中 +的自定义代码。 + +## 设计目标 + +CloudEvents 通常用于分布式系统，以允许服务在开发过程中松耦合，独立部署，之后可以连接以创建新的应用程序。 + +CloudEvents 规范的目标是定义允许服务生产或消费事件的事件系统的互操作性， +其中生产者和消费者可以独立开发和部署。 生产者可以在没有消费者监听时就生成事件， +消费者也可以表达对尚未生成的事件或事件类的兴趣。值得注意的是，这项工作产生的规范侧重于事件格式的互操作性 +以及它在通过各种协议（例如 HTTP）发送时的显示方式。我们不关注事件生产者或事件消费者的处理模型。 + +CloudEvents的核心规范中定义了一组称之为属性的元数据， +它们描述了在系统之间传输的事件以及这些元数据片段应如何显示在该消息中。 +这些元数据是，将请求路由到适当组件并帮助该组件正确处理事件，所需的最小信息集。 +因此，某些事件本身的数据可能会作为 CloudEvent 属性集的一部分而被复制， +但这样做仅是为了能够正确传递和处理消息。那些不用于该目的的数据应放置在事件（数据）本身中。 + +此外，本规范中假设协议层所需，用来将消息传递到目标系统的元数据应完全由协议处理， +因此不包含在 CloudEvents 属性中。 有关更多详细信息，请参阅非目标部分。 + +除了这些属性的定义之外，规范还描述了关于如何序列化 +不同格式（例如 JSON）和协议（例如 HTTP、AMQP、Kafka）事件。 + +一些协议本身支持将多个事件批处理到单个 API 调用中。 +为了提升系统间的互操作性，是否以及如何实现批处理将由协议自己决定。 +相关详细信息可以在协议绑定或协议规范中找到。 +成批的CloudEvents并没有语义，也没有排序。 +[中间人](spec.md#intermediary)可以添加或删除批处理以及将事件分配给不同的批处理。 ### Non-Goals From de6adfe4fcfe9ca23d778c2df5779154e0956127 Mon Sep 17 00:00:00 2001 From: JieDing Date: Sun, 7 Nov 2021 21:34:51 +0800 Subject: [PATCH 34/60] Update primer.md Signed-off-by: JieDing --- primer.md | 210 +++++++++++++++++++++++------------------------------- 1 file changed, 90 insertions(+), 120 deletions(-) diff --git a/primer.md b/primer.md index 85c4b51d6..79a3916e1 100644 --- a/primer.md +++ b/primer.md @@ -95,132 +95,102 @@ CloudEvents的核心规范中定义了一组称之为属性的元数据， 成批的CloudEvents并没有语义，也没有排序。 [中间人](spec.md#intermediary)可以添加或删除批处理以及将事件分配给不同的批处理。 -### Non-Goals - -The following are considered beyond the scope of the specification: - -- Function build and invocation process -- Language-specific runtime APIs -- Selecting a single identity/access control system -- Inclusion of protocol-level routing information -- Event persistence processes - -The CloudEvents spec will not include protocol-level routing information (e.g. -a destination URL to which the event is being sent). This is a common suggestion -by those new to the concepts of CloudEvents. After much deliberation, the -working group has come to the conclusion that routing is unnecessary in the -spec: any protocol (e.g. HTTP, MQTT, XMPP, or a Pub/Sub bus) already -defines semantics for routing. For example, the CloudEvents -[HTTP binding](http-protocol-binding.md) dictates headers and request body -contents. CloudEvents don't need to include a destination URL in the spec to be -HTTP compatible; the HTTP spec already includes one in the -[Request-Line](https://tools.ietf.org/html/rfc2616#section-5.1). - -Routing information is not just redundant, it detracts. CloudEvents should -increase interoperability and decouple the producer and consumer of events. -Prohibiting routing information from the events format allows CloudEvents to be -redelivered to new actions, or to be delivered over complex relays that include -multiple channels. For example, a CloudEvent that was intended for a webhook -should be deliverable to a dead-letter queue if the webhook address is -unavailable. That dead-letter queue should be able to feed events to new actions -that the original event emitter never imagined. - -The CloudEvents that are produced and consumed within and across systems trigger -behaviors that derive value. As such, archiving and/or replaying events can be -valuable for debugging or replication purposes. However, persisting an event -removes the contextual information available during transmission such as the -identity and rights of the producer, fidelity validation mechanisms, or -confidentiality protections. Additionally, persistence can add complexity and -challenge to meeting user's requirements. For example, the repeated use of a -private key for encryption or signing purposes increases the information -available to attackers and thereby reduces security. It is expected that -attributes may be defined that facilitate meeting persistence requirements but -it is expected that these will continuously evolve along with industry best -practices and advancements. +### 非目标 + +以下内容不在本规范的范围之内： + +- 函数的构建和调用过程 +- 特定语言的运行时 APIs +- 选择单一身份认证或访问控制的系统 +- 包含协议级路由信息 +- 事件持久化过程 + +就连那些刚接触 CloudEvents 概念的人都普遍建议 +CloudEvents 规范不应包括协议级路由信息（例如，将事件发送到的目标的URL）。 +经过深思熟虑，工作组得出的结论是，CloudEvents规范中不需要路由信息： +因为任何现有的协议（例如 HTTP、MQTT、XMPP 或 Pub/Sub 总线）都已经定义了路由语义。 +例如，CloudEvents [HTTP 绑定](http-protocol-binding.md) 规定了头部和请求正文内容。 +CloudEvents 不需要在规范中包含目标 URL 即可与 HTTP 兼容；HTTP 规范已经在 +[请求行](https://tools.ietf.org/html/rfc2616#section-5.1) 中包含了所需的目标URL。 + +路由信息不仅是多余的，而且是有害的。 +CloudEvents 应该增加互操作性并解耦事件的生产者和消费者。 +禁止来自事件格式的路由信息允许将 CloudEvents 重新传送到新操作，或通过包含多个通道的复杂中继传送。 +例如，如果 Webhook 地址不可用，则用于 Webhook 的 CloudEvent 应可传送到死信队列。 +死信队列应该能够将事件提供给原始事件发射器从未想象过的新操作。 + +在系统内和跨系统生产和消费的 CloudEvent能够触发产生价值的行为。 +因此，对于调试或复制的目的而言，存档和或重放事件可能很有价值。 +但是，持久化事件会删除传输期间可用的上下文信息，例如生产者的身份和权利、保真验证机制或机密性保护。 +此外，持久化会增加满足用户需求的复杂性和挑战。 +例如，出于加密或签名目的重复使用私钥会增加攻击者可用的信息，从而降低安全性。 +因此我们推测，可以定义有助于满足持久性要求的属性，但这些属性可能随着行业最佳实践和进步而不断发展。 ## Architecture +CloudEvents 规范集定义了四种有助于形成分层架构模型的不同类型的协议元素。 +基本规范定义了一个抽象信息模型，该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 -The CloudEvents specification set defines four different kinds of protocol -elements that form a layered architecture model. - -1. The [base specification](spec.md) defines an abstract information model made - up of attributes (key-value pairs) and associated rules for what constitutes - a CloudEvent. -2. The [extensions](./spec.md#extension-context-attributes) add use-case - specific and potentially overlapping sets of extension attributes and - associated rules, e.g. to support different tracing standards. -3. The event format encodings, e.g. [JSON](json-format.md), define how the - information model of the base specification together with the chosen - extensions is encoded for mapping it to header and payload elements of an - application protocol. -4. The protocol bindings, e.g. [HTTP](http-protocol-binding.md), defines how - the CloudEvent is bound to an application protocol's transport frame, in the - case of HTTP to the HTTP message. The protocol binding does not constrain - how the transport frame is used, meaning that the HTTP binding can be used - with any HTTP method and with request and response messages. - -If required to assure broader interoperability, the CloudEvents specification -set provides specific constraints for event delivery using a particular -application protocol. The [HTTP Webhook](http-webhook.md) specification is not -specific to CloudEvents and can be used to post any kind of one-way event and -notifications to a conformant HTTP endpoint. However, the lack of such a -specification elsewhere makes it necessary for CloudEvents to define it. - -### Protocol Error Handling - -The CloudEvents specification, for the most part, does not dictate a processing -model associated with the creation or processing of CloudEvents. As such, if -there are errors during the processing of a CloudEvent, the software -encountering the error is encouraged to use the normal protocol-level error -reporting to report them. - -## Versioning of Attributes - -For certain CloudEvents attributes, the entity or data model referenced by its -value might change over time. For example, `dataschema` might reference one -particular version of a schema document. Often these attribute values will then -distinguish each variant by including some version-specific string as part of -its value. For example, a version number (`v1`, `v2`), or a date (`2018-01-01`) -might be used. - -The CloudEvents specification does not mandate any particular pattern to be -used, or even the use of version strings at all. This decision is up to each -event producer. However, when a version-specific string is included, care should -be taken whenever its value changes as event consumers might be reliant on the -existing value and thus a change could be interpreted as a "breaking change". -Some form of communication between producers and consumers should be established -to ensure the event consumers know what possible values might be used. In -general, this is true for all CloudEvents attributes as well. - -## CloudEvent Attributes - -This section provides additional background and design points related to some of -the CloudEvent attributes. +1. [基本规范](spec.md) 定义了一个抽象信息模型， + 该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 +2. [扩展](./spec.md#extension-context-attributes) + 添加了特定于用例且可能重叠的扩展属性集和相关规则，如支持不同的追踪标准的规则。 +3. 事件格式编码,如 [JSON](json-format.md), 定义了基本规范的信息模型与所选扩展的编码方式， + 以将其映射到应用程序协议的头部和负载元素。 +4. 协议绑定, 如. [HTTP协议绑定](http-protocol-binding.md), + 在HTTP to HTTP的情况下， + 定义了 CloudEvent 如何绑定到应用程序协议的传输层 。 + 协议绑定不限制传输层的使用方式，这意味着 HTTP绑定可用于任何 HTTP方法以及请求和响应消息。 + +为了确保更广泛的互操作性，CloudEvents规范集为使用专有应用协议的事件传输提供了特定约束。 +[HTTP Webhook](http-webhook.md)规范并非特定于 CloudEvents， +而是可用于将任何类型的单向事件和通知发布到符合标准的 HTTP 端点。 +但是，由于其他地方缺乏此类规范，因此 CloudEvents 需要对其进行定义。 + +### 协议错误处理 + +CloudEvents 规范在很大程度上并未规定与 CloudEvents 的创建或处理相关联的处理模型。 +因此，如果在处理 CloudEvent 过程中出现错误， +请使用正常的协议级错误处理机制进行处理。 + +## 属性版本 + +对于某些 CloudEvents 属性，由其值引用的实体或数据模型可能会随时间变化。 +例如，`dataschema`可能引用模式文档的一个特定版本。 +通常，这些属性值会通过将一些特定于版本的字符串作为其值的一部分来区分每个变体。 +例如，可能会加入版本号 (v1, v2) 或日期 (2018-01-01)来区分。 + +CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强制使用版本字符串。 +是否使用完全取决于每个事件生产者。 +但是，当使用特定版本的字符串时，每当其值发生变化时都应注意， +因为事件消费者可能依赖于现有值，因此更改可能被解释为“破坏性更改”。 +应该在生产者和消费者之间建立某种形式的通信，以确保事件消费者知道能使用哪些可能的值。 +通常，这也适用于所有 CloudEvents 属性。 + +## CloudEvent 属性 + +本节介绍了与CloudEvent 属性相关的其他背景和设计要点。 ### id -The `id` attribute is meant to be a value that is unique across all events -related to one event source (where each event source is uniquely identified by -its CloudEvents `source` attribute value). While the exact value used is -producer defined, receivers of CloudEvents from a single event source can be -assured that no two events will share the same `id` value. The only exception to -this is if some replay of the event is supported, and in those cases, the `id` -can then be used to detect this. - -Since a single occurrence may result in the generation of more than one event, -in the cases where all of those events are from the same event source, each -CloudEvent constructed will have a unique `id`. Take the example of the creation -of a DB entry, this one occurrence might generate a CloudEvent with a type of -`create` and a CloudEvent with a type of `write`. Each of those CloudEvents -would have a unique `id`. If there is the desire for some correlation between -those two CloudEvents to indicate they are both related to the same occurrence, -then some additional data within the CloudEvent would be used for that purpose. - -In this respect, while the exact value chosen by the event producer might be -some random string, or a string that has some semantic meaning in some other -context, for the purposes of this CloudEvent attribute those meanings are not -relevant and therefore using `id` for some other purpose beyond uniqueness -checking is out of scope of the specification and not recommended. +`id` 属性是一个在同一事件源下所有事件中用来标识事件唯一的值 +（其中每个事件源由其 CloudEvents `source`属性唯一标识）。 +虽然`id`使用的确切值是生产者定义的， +但可以确保来自单个事件源的 CloudEvents 消费者不会有两个事件共享相同的 id 值。 +唯一的例外是如果支持事件的重播，在这些情况下，可以使用 id 来检测这一点。 + +由于一次事件的发生可能导致生成多个cloud event， +在所有这些事件都来自同一事件源的情况下， +生成的每个 CloudEvent 将具有唯一的 `id`。 +以创建数据库条目为例，这一事件的发生可能会生成一个类型为 create 的 CloudEvent +和一个类型为 write 的 CloudEvent。 +这两个 CloudEvents 各自都有一个唯一的 ID。 +如果需要在这两个 CloudEvent 之间建立某种关联以表明它们都与同一事件相关， +那么可以使用 CloudEvent 中的一些附加数据来实现该目的。 + +从这方面来看，虽然事件生产者对`id`的使用可能是某个随机字符串， +或者在其他上下文中具有某种语义的字符串， +但对于此 CloudEvent 属性而言，这些含义并不成立， +因此本规范不建议将 `id` 用于除了唯一性检查之外的其他目的。 ## CloudEvent Attribute Extensions From a9baebed98b435c029f4818fe922b58cb637a051 Mon Sep 17 00:00:00 2001 From: JieDing Date: Mon, 8 Nov 2021 11:24:27 +0800 Subject: [PATCH 35/60] Update primer.md Signed-off-by: JieDing --- primer.md | 353 +++++++++++++++++++++++------------------------------- 1 file changed, 148 insertions(+), 205 deletions(-) diff --git a/primer.md b/primer.md index 79a3916e1..e8ea85e9b 100644 --- a/primer.md +++ b/primer.md @@ -8,7 +8,7 @@ ## 目录 -- [历史](#history) +- [历史](#历史) - [CloudEvents 概念](#cloudevents-concepts) - [设计目标](#design-goals) - [架构](#architecture) @@ -16,7 +16,7 @@ - [CloudEvent 属性](#cloudevent-attributes) - [CloudEvent 属性扩展](#cloudevent-attribute-extensions) - [生产 CloudEvents](#creating-cloudevents) -- [Qualifying 协议和编码](#qualifying-protocols-and-encodings) +- [合格的协议与编码](#qualifying-protocols-and-encodings) - [Proprietary 协议和编码](#proprietary-protocols-and-encodings) - [Prior Art](#prior-art) - [Roles](#roles) @@ -188,210 +188,153 @@ CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强 那么可以使用 CloudEvent 中的一些附加数据来实现该目的。 从这方面来看，虽然事件生产者对`id`的使用可能是某个随机字符串， -或者在其他上下文中具有某种语义的字符串， +或者在其它上下文中具有某种语义的字符串， 但对于此 CloudEvent 属性而言，这些含义并不成立， -因此本规范不建议将 `id` 用于除了唯一性检查之外的其他目的。 - -## CloudEvent Attribute Extensions - -In order to achieve the stated goals, the specification authors will attempt to -constrain the number of metadata attributes they define in CloudEvents. To that -end, attributes defined by this project will fall into three categories: - -- required -- optional -- extensions - -As the category names imply, "required" attributes will be the ones that the -group considers vital to all events in all use cases, while "optional" ones will -be used in a majority of the cases. Both of the attributes in these cases will -be defined within the specification itself. - -When the group determines that an attribute is not common enough to fall into -those two categories but would still benefit from the level of interoperability -that comes from being well-defined, then they will be placed into the -"extensions" category and put into -[documented extensions](documented-extensions.md). The specification defines how -these extension attributes will appear within a CloudEvent. - -In determining which category a proposed attribute belongs, or even if it will -be included at all, the group uses use-cases and user-stories to explain the -rationale and need for them. This supporting information will be added to the -[Prior Art](#prior-art) section of this document. - -Extension attributes to the CloudEvent specification are meant to be additional -metadata that needs to be included to help ensure proper routing and processing -of the CloudEvent. Additional metadata for other purposes, that is related to -the event itself and not needed in the transportation or processing of the -CloudEvent, should instead be placed within the proper extensibility points of -the event (`data`) itself. - -Extension attributes should be kept minimal to ensure the CloudEvent can be -properly serialized and transported. For example, the Event producers should -consider the technical limitations that might be encountered when adding -extensions to a CloudEvent. For example, the -[HTTP Binary Mode](http-protocol-binding.md#31-binary-content-mode) uses HTTP -headers to transport metadata; most HTTP servers will reject requests with -excessive HTTP header data, with limits as low as 8kb. Therefore, the aggregate -size and number of extension attributes should be kept minimal. - -If an extension becomes popular then the specification authors might consider -moving it into the specification as a core attribute. This means that the -extension mechanism/process can be used as a way to vet new attributes prior to -formally adding them to the specification. - -### JSON Extensions - -As mentioned in the [Attributes](json-format.md#2-attributes) section of the -[JSON Event Format for CloudEvents](json-format.md) specification, CloudEvent -extension attributes are serialized as siblings to the specification defined -attributes - meaning, at the top-level of the JSON object. The authors of the -specification spent a long time considering all options and decided that this -was the best choice. Some of the rationale follows. - -Since the specifications follow [semver](https://semver.org/), this means that -new properties can be defined by future versions of the core specification -without requiring a major version number change - as long as these properties -are optional. In those cases, consider what an existing consumer would do with a -new (unknown) top-level property. While it would be free to ignore it, since it -is optional, in most cases it is believed that these properties would still want -to be exposed to the application receiving those events. This would allow those -applications to support these properties even if the infrastructure doesn't. -This means that unknown top-level properties (regardless of who defined them - -future versions of the spec or the event producer) are probably not going to be -ignored. So, while some other specifications define a specific property under -which extensions are placed (e.g. a top-level `extensions` property), the -authors decided that having two different locations within an incoming event for -unknown properties could lead to interoperability issues and confusion for -developers. - -Often extensions are used to test new potential properties of specifications -prior to them being formally adopted. If there were an `extensions` type of -property, in which this new property was serialized, then if that property were -to ever be adopted by the core specification it would be promoted (from a -serialization perspective) from the `extensions` property to be a top-level -property. If we assume that this new property will be optional, then as it is -adopted by the core specification it will be just a minor version increment, and -all existing consumers should still continue to work. However, consumers will -not know where this property will appear - in the `extensions` property or as a -top-level property. This means they might need to look in both places. What if -the property appears in both place but with different values? Will producers -need to place it in both places since they could have old and new consumers? -While it might be possible to define clear rules for how to solve each of the -potential problems that arise, the authors decided that it would be better to -simply avoid all of them in the first place by only having one location in the -serialization for unknown, or even new, properties. It was also noted that the -HTTP specification is now following a similar pattern by no longer suggesting -that extension HTTP headers be prefixed with `X-`. - -## Creating CloudEvents - -The CloudEvents specification purposely avoids being too prescriptive about how -CloudEvents are created. For example, it does not assume that the original event -source is the same entity that is constructing the associated CloudEvent for -that occurrence. This allows for a wide variety of implementation choices. -However, it can be useful for implementors of the specification to understand -the expectations that the specification authors had in mind as this might help -ensure interoperability and consistency. - -As mentioned above, whether the entity that generated the initial event is the -same entity that creates the corresponding CloudEvent is an implementation -choice. However, when the entity that is constructing/populating the CloudEvents -attributes is acting on behalf of the event source, the values of those -attributes are meant to describe the event or the event source and not the -entity calculating the CloudEvent attribute values. In other words, when the -split between the event source and the CloudEvents producer are not materially -significant to the event consumers, the spec defined attributes would typically -not include any values to indicate this split of responsibilities. - -This isn't to suggest that the CloudEvents producer couldn't add some additional -attributes to the CloudEvent, but those are outside the scope of the -interoperability defined attributes of the spec. This is similar to how an HTTP -proxy would typically minimize changes to the well-defined HTTP headers of an -incoming message, but it might add some additional headers that include -proxy-specific metadata. - -It is also worth noting that this separation between original event source and -CloudEvents producer could be small or large. Meaning, even if the CloudEvent -producer were not part of the original event source's ecosystem, if it is acting -on behalf of the event source, and its presence in the flow of the event is not -meaningful to event consumers, then the above guidance would still apply. - -When an entity is acting as both a receiver and sender of CloudEvents for the -purposes of forwarding, or transforming, the incoming event, the degree to which -the outbound CloudEvent matches the inbound CloudEvent will vary based on the -processing semantics of this entity. In cases where it is acting as proxy, where -it is simply forwarding CloudEvents to another event consumer, then the outbound -CloudEvent will typically look identical to the inbound CloudEvent with respect -to the spec defined attributes - see previous paragraph concerning adding -additional attributes. - -However, if this entity is performing some type of semantic processing of the -CloudEvent, typically resulting in a change to the value of the `data` -attribute, then it may need to be considered a distinct "event source" from the -original event source. And as such, it is expected that CloudEvents attributes -related to the event producer (such as `source` and `id`) would be changed from -the incoming CloudEvent. - -## Qualifying Protocols and Encodings - -The explicit goal of the CloudEvents effort, as expressed in the specification, -is "describing event data in a common way" and "to define interoperability of -event systems that allow services to produce or consume events, where the -producer and consumer can be developed and deployed independently". - -The foundations for such interoperability are open data formats and open -protocols, with CloudEvents aiming to provide such an open data format and -projections of its data format onto commonly used protocols and with commonly -used encodings. - -While each software or service product and project can obviously make its own -choices about which form of communication it prefers, its unquestionable that a -proprietary protocol that is private to such a product or project does not -further the goal of broad interoperability across producers and consumers of -events. - -Especially in the area of messaging and eventing, the industry has made -significant progress in the last decade in developing a robust and broadly -supported protocol foundation, like HTTP 1.1 and HTTP/2 as well as WebSockets or -events on the web, or MQTT and AMQP for connection-oriented messaging and -telemetry transfers. - -Some widely used protocols have become de-facto standards emerging out of strong -ecosystems of top-level consortia of three or more companies, and some out of -the strong ecosystems of projects released by a single company, and in either -case largely in parallel to the evolution of the previously mentioned standards -stacks. - -The CloudEvents effort shall not become a vehicle to even implicitly endorse or -promote project- or product-proprietary protocols, because that would be -counterproductive towards CloudEvents' original goals. - -For a protocol or encoding to qualify for a core CloudEvents event format or -protocol binding, it must belong to either one of the following categories: - -- The protocol has a formal status as a standard with a widely-recognized - multi-vendor protocol standardization body (e.g. W3C, IETF, OASIS, ISO) -- The protocol has a "de-facto standard" status for its ecosystem category, - which means it is used so widely that it is considered a standard for a given - application. Practically, we would like to see at least one open source - implementation under the umbrella of a vendor-neutral open-source organization - (e.g. Apache, Eclipse, CNCF, .NET Foundation) and at least a dozen independent - vendors using it in their products/services. - -Aside from formal status, a key criterion for whether a protocol or encoding -shall qualify for a core CloudEvents event format or protocol binding is -whether the group agrees that the specification will be of sustained practical -benefit for any party that is unrelated to the product or project from which the -protocol or encoding emerged. A base requirement for this is that the protocol -or encoding is defined in a fashion that allows alternate implementations -independent of the product or project's code. - -All other protocol and encoding formats for CloudEvents are welcome to be -included in a list pointing to the CloudEvents binding information in the -respective project's own public repository or site. - -## Proprietary Protocols and Encodings +因此本规范不建议将 `id` 用于除了唯一性检查之外的其它目的。 + +## CloudEvent 属性扩展 + +为了实现规范的设计目标， +规范作者将尝试限制他们在 CloudEvents 中定义的元数据属性的数量。 +为此，该项目定义的属性将分为以下三类： + +- 必要属性 +- 可选属性 +- 扩展属性 + +正如类别名称所暗示的那样， +“必要”属性是工作组认为在任何情况下，对所有事件都至关重要的属性， +而“可选”属性将在大多数情况下使用。 这些情况下的两个属性都在本规范中定义了出来。 + +当工作组考虑到某些属性不够常见而不能归入上述两个类别， +但此类属性的良好定义仍会使系统间的互操作性级别受益， +则将这些属性放入了“扩展”类别并记录在[扩展文档](documented-extensions.md)中， +本规范定义了这些扩展属性在 CloudEvent 中的显示方式。 + +在确定提议的属性属于哪个类别时， +工作组使用现有的用例和用户故事来解释它们的基本原理和需求。 +相关信息将添加到本文档的[现有技术](#prior-art)部分。 + +CloudEvent 规范的扩展属性是需要包含的附加元数据，它们能确保合适的路由和正确处理CloudEvent。 +用于其它目的的附加元数据， +即那些与事件本身相但在 CloudEvent 的传输或处理中不需要的元数据， +应改为放置在事件 (`data`)的扩展点内。 + +扩展属性应保持最少，以确保 CloudEvent 可以正确序列化和传输。 +事件生产者应该考虑在向 CloudEvent 添加扩展时可能遇到的技术限制。 +例如，[HTTP Binary Mode](http-protocol-binding.md#31-binary-content-mode) +使用 HTTP 头来传输元数据； +大多数 HTTP 服务器会拒绝包含过多 HTTP 头部数据的请求，要求限制其低至 8kb。 +因此，扩展属性的大小和数量应保持最小。 + +如果扩展变得流行，那么规范作者可能会考虑将其作为核心属性移入规范。 +这意味着在正式将新属性添加到规范之前，扩展机制/过程可用作审查新属性的一种方式。 + +### JSON 扩展 + +如 [CloudEvents JSON 事件格式](json-format.md)中 +[属性](json-format.md#2-attributes)部分所述， +CloudEvent 扩展属性与已定义属性(必要属性、可选属性)在序列化时处于同一等级 - +也就是说，它们都是 JSON 对象的顶层属性。 +CloudEvent的作者花了很长时间考虑所有选项，并认为这是最好的选择。 +理由如下： + +由于CloudEvents规范遵循 [semver](https://semver.org/)， +这意味着只要新属性是可选属性，它们可以由核心规范的未来版本定义，而无需更改主要版本。 +在这些情况下，请考虑现有消费者将如何使用新的（未知）顶级属性。 +虽然消费者可以随意忽略它，因为它是可选的， +但在大多数情况下，这些属性仍然希望向接收这些事件的应用公开。 +这将允许这些应用程序支持这些属性，即使基础设施不支持。 +这意味着未知的顶级属性（无论是谁定义的——规范的未来版本或事件生产者）可能不会被忽略。 +因此，虽然其它一些规范定义了放置扩展的特定属性（例如顶级`extensions`属性）， +但作者认为在传入事件中具有两个不同位置的未知属性可能会导致互操作性问题和开发人员的混淆。 + +扩展属性通常用于测试那些被规范正式采用之前的潜在属性。 +如果有一个`extensions`类型的属性，这个新属性已经被序列化， +那么如果该属性被核心规范采用，它将从`extensions`属性提升（从序列化的角度）为顶级属性。 +如果我们假设这个新属性是可选的，那么当它被核心规范采用时， +它只是一个小版本增量，所有现有的消费者仍然会继续工作。 +但是，消费者将不知道此属性将出现在何处 - 在扩展属性中或是作为顶级属性。 +这意味着他们可能需要同时查看两个地方。 +如果属性出现在两个地方但具有不同的值怎么办？ +生产者是否需要将它放在两个地方，因为他们可能有新老消费者？ +虽然有可能为如何解决出现的每个潜在问题定义明确的规则， +但作者认为一个避免这些问题的更好的办法是在序列化中只有一个位置来放置未知的甚至是新的属性。 +作者还注意到 HTTP 规范现在遵循类似的模式，不再建议扩展 HTTP 头部以 X- 为前缀。 + +## 生产 CloudEvents + +CloudEvents 规范有意避免将CloudEvents 的创建方式设计的过于死板。 +例如，它不假定原始事件源必须是该事件构造关联 CloudEvent 的同一实体。 +这允许多种实现方式。 +但是，对于规范的实现者来说，理解规范作者心中的期望是很有用的，因为这将有助于确保互操作性和一致性。 + +如上所述，生成初始事件的实体是否与创建相应 CloudEvent 的实体相同是由实现决定的。 +但是，当构建/填充 CloudEvents 属性的实体代表事件源进行操作时，这些属性的值是用来描述事件或事件源， +而不是计算 CloudEvent 属性值的实体的。 +换句话说，当事件源和 CloudEvents 生产者之间的分离对事件使用者没有实质性意义时， +规范定义的属性通常不会包含任何值来指示这种职责分离。 + +这并不是说 CloudEvents 生产者不能向 CloudEvent 添加一些额外的属性， +但这些属性超出了规范的互操作性定义属性的范围。 +这类似于 HTTP 代理通常如何最大限度地减少对传入消息的明确定义的 HTTP 头部的更改， +但它可能会添加一些额外的头部，其中包括一些特定代理的元数据。 + +还值得注意的是，原始事件源和 CloudEvents 生产者之间的这种分离可大可小。 +意思是，即使 CloudEvent 生产者不是原始事件源生态系统的一部分， +如果它代表事件源行事，并且它在事件流中的存在对事件消费者没有意义，那么上述指导仍然适用。 + +当实体同时充当 CloudEvents 的接收者和发送者以转发或转换传入事件时， +出站 CloudEvent 与入站 CloudEvent 匹配的程度将根据该实体的处理语义而有所不同。 +在它充当代理的情况下，它只是将 CloudEvents 转发给另一个事件消费者， +那么出站 CloudEvent 通常看起来与入站 CloudEvent 就规范定义的属性相同 +- 请参阅上一段有关添加其他属性的内容。 + +但是，如果此实体正在执行 CloudEvent 的某种类型的语义处理， +通常会导致`data`属性值发生更改， +则可能需要将其视为与原始事件源不同的“事件源”。 +因此，预计与事件生产者相关的 CloudEvents 属性（例如`source` and `id`） +将从传入的 CloudEvent 中更改。 + +## 合格的协议与编码 + +正如规范中所表达的，CloudEvents 工作的明确目标是 +“以通用方式描述事件数据”且 +“定义允许服务产生或消费事件的事件系统的互操作性，其中生产者和消费者可以被独立开发和部署”。 + +这种互操作性的基础是开放的数据格式和协议， +CloudEvents 旨在提供这种开放的数据格式，并将其数据格式映射到常用协议和常用编码上。 + +虽然每个软件或服务产品和项目都可以自己选择自己喜欢的通信形式， +但毫无疑问，这种产品或项目私有的专有协议无法进一步实现跨生产者和消费者的广泛互操作性的目标。 + +特别是在消息传递和事件处理领域，该行业在过去十年中开发出了强大且受到广泛支持的协议 +例如 HTTP 1.1 和 HTTP/2 以及 WebSockets 或 Web 上的事件，或者 MQTT 和 AMQP +用于面向连接的消息传递和遥测传输的协议。 + +一些广泛使用的协议已经成为事实上的标准，这些协议来自三个或更多公司的顶级财团的强大生态系统， +还有一些来自单个公司发布的强大项目生态系统，在任何一种情况下都与前面提到的标准栈的演变相一致。 + +CloudEvents的努力不应成为认可或推广项目或产品专有协议的工具， +因为这与CloudEvents 的原始目标背道而驰。 + +要使协议或编码符合核心 CloudEvents 事件格式或协议绑定的条件，它必须属于以下任一类别： + +- 该协议具有广泛认可的多供应商协议标准化机构（例如 W3C、IETF、OASIS、ISO）的正式标准地位 +- 该协议在其生态系统类别中具有“事实上的标准”地位， + 这意味着它被广泛使用，甚至被认为是给定应用程序的标准。 + 实际上，我们希望在供应商中立的开源组织（例如 Apache、Eclipse、CNCF、.NET 基金会）的保护伞下 + 看到至少一个开源实现， + 并且至少有十几个独立供应商在他们的产品中使用它的产品或服务。 + +除了正式状态之外，协议或编码是否符合核心 CloudEvents 事件格式或协议绑定的一个关键标准是， +该组织是否认为协议或编码出现后，该规范对与产品或项目无关的任何一方具有持续的实际利益。 +对此的基本要求是协议或编码的定义方式允许独立于产品或项目代码的替代实现。 + +欢迎将 CloudEvents 的所有其他协议和编码格式 +包含在指向相应项目自己的公共存储库或站点中的 CloudEvents binding信息的列表中。 + +## 专有的协议与编码 To encourage adoption of CloudEvents, this repository will collect CloudEvent specs for proprietary protocols and encodings without endorsement. Repository From d0a93aa2fe1288871e2bb32fd3153d2eb4d45663 Mon Sep 17 00:00:00 2001 From: JieDing Date: Mon, 8 Nov 2021 17:18:09 +0800 Subject: [PATCH 36/60] Update primer.md Signed-off-by: JieDing --- primer.md | 468 +++++++++++++++++++++++------------------------------- 1 file changed, 195 insertions(+), 273 deletions(-) diff --git a/primer.md b/primer.md index e8ea85e9b..9681d2a84 100644 --- a/primer.md +++ b/primer.md @@ -9,18 +9,18 @@ ## 目录 - [历史](#历史) -- [CloudEvents 概念](#cloudevents-concepts) -- [设计目标](#design-goals) -- [架构](#architecture) -- [属性版本](#versioning-of-attributes) -- [CloudEvent 属性](#cloudevent-attributes) -- [CloudEvent 属性扩展](#cloudevent-attribute-extensions) -- [生产 CloudEvents](#creating-cloudevents) -- [合格的协议与编码](#qualifying-protocols-and-encodings) -- [Proprietary 协议和编码](#proprietary-protocols-and-encodings) -- [Prior Art](#prior-art) -- [Roles](#roles) -- [Value Proposition](#value-proposition) +- [CloudEvents 概念](#CloudEvents-概念) +- [设计目标](#设计目标) +- [架构](#架构) +- [属性版本](#属性版本) +- [CloudEvent 属性](#CloudEvent-属性) +- [CloudEvent 属性扩展](#CloudEvent-属性扩展) +- [生产 CloudEvents](#生产CloudEvents) +- [合格的协议与编码](#合格的协议与编码) +- [Proprietary 协议和编码](#专有的协议与编码) +- [Prior Art](#现有技术) +- [Roles](#角色) +- [Value Proposition](#价值主张) - [Existing Event Formats](#existing-event-formats) ## 历史 @@ -33,7 +33,7 @@ Serverless相关技术并为CNCF推荐相关领域的未来发展计划。其中 尽管CloudEvents起初是作为Serverless工作组的项目进行的，但随着CloudEvents规范完成它v0.1版本的里程碑， 技术监管委员会批准了CloudEvents工作作为一个新的独立的CNCF沙箱级项目。 -## CloudEvents 概念 +## CloudEvents-概念 一个[事件](spec.md#event)包含了[事件发生](spec.md#occurrence)的上下文和相关数据。 事件的相关数据可以用来唯一标识一件事件的发生。 @@ -126,7 +126,7 @@ CloudEvents 应该增加互操作性并解耦事件的生产者和消费者。 例如，出于加密或签名目的重复使用私钥会增加攻击者可用的信息，从而降低安全性。 因此我们推测，可以定义有助于满足持久性要求的属性，但这些属性可能随着行业最佳实践和进步而不断发展。 -## Architecture +## 架构 CloudEvents 规范集定义了四种有助于形成分层架构模型的不同类型的协议元素。 基本规范定义了一个抽象信息模型，该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 @@ -166,7 +166,7 @@ CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强 应该在生产者和消费者之间建立某种形式的通信，以确保事件消费者知道能使用哪些可能的值。 通常，这也适用于所有 CloudEvents 属性。 -## CloudEvent 属性 +## CloudEvent-属性 本节介绍了与CloudEvent 属性相关的其他背景和设计要点。 @@ -192,7 +192,7 @@ CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强 但对于此 CloudEvent 属性而言，这些含义并不成立， 因此本规范不建议将 `id` 用于除了唯一性检查之外的其它目的。 -## CloudEvent 属性扩展 +## CloudEvent-属性扩展 为了实现规范的设计目标， 规范作者将尝试限制他们在 CloudEvents 中定义的元数据属性的数量。 @@ -262,7 +262,7 @@ CloudEvent的作者花了很长时间考虑所有选项，并认为这是最好 但作者认为一个避免这些问题的更好的办法是在序列化中只有一个位置来放置未知的甚至是新的属性。 作者还注意到 HTTP 规范现在遵循类似的模式，不再建议扩展 HTTP 头部以 X- 为前缀。 -## 生产 CloudEvents +## 生产CloudEvents CloudEvents 规范有意避免将CloudEvents 的创建方式设计的过于死板。 例如，它不假定原始事件源必须是该事件构造关联 CloudEvent 的同一实体。 @@ -336,277 +336,200 @@ CloudEvents的努力不应成为认可或推广项目或产品专有协议的工 ## 专有的协议与编码 -To encourage adoption of CloudEvents, this repository will collect CloudEvent -specs for proprietary protocols and encodings without endorsement. Repository -maintainers are not responsible for creating, maintaining, or notifying -maintainers of proprietary specs of drift from the CloudEvents spec. - -Proprietary specs will be hosted in their own repository or documentation site, -and collected in the [proprietary-specs](proprietary-specs.md) file. Proprietary -specs should follow the same format as the other specs for core protocols and -encodings. - -Proprietary specs will receive less scrutiny than a core spec, and as the -CloudEvents spec evolves, it is the responsibility of the maintainers of the -respective protocols and encodings to keep specs in sync with the CloudEvents -spec. If a proprietary spec falls too far out of date, CloudEvents may mark the -link to that spec as deprecated or remove it. - -In the case that multiple, incompatible specs are created for the same protocol, -the repository maintainers will be agnostic about which spec is correct and list -links to all specs. - -## Prior Art - -This section describes some of the input material used by the group during the -development of the CloudEvent specification. - -### Roles - -The list below enumerates the various participants, and scenarios, that might be -involved in the producing, managing or consuming of events. - -In these the roles of event producer and event consumer are kept distinct. A -single application context can always take on multiple roles concurrently, -including being both a producer and a consumer of events. - -1. Applications produce events for consumption by other parties, for instance - for providing consumers with insights about end-user activities, state - changes or environment observations, or for allowing complementing the - application's capabilities with event-driven extensions. - - Events are typically produced related to a context or a producer-chosen - classification. For example, a temperature sensor in a room might be - context-qualified by mount position, room, floor, and building. A sports - result might be classified by league and team. - - The producer application could run anywhere, such as on a server or a device. - - The produced events might be rendered and emitted directly by the producer or - by an intermediary; as example for the latter, consider event data - transmitted by a device over payload-size-constrained networks such as - LoRaWAN or ModBus, and where events compliant to this specification will be - rendered by a network gateway on behalf of the producer. - - For example, a weather station transmits a 12-byte, proprietary event payload - indicating weather conditions once every 5 minutes over LoRaWAN. A LoRaWAN - gateway is then used to publish the event to an Internet destination in the - CloudEvents format. The LoRaWAN gateway is the event producer, publishing on - behalf of the weather station, and will set event metadata appropriately to - reflect the source of the event. - -2. Applications consume events for the purposes such as display, archival, - analytics, workflow processing, monitoring the condition and/or providing - transparency into the operation of a business solution and its foundational - building blocks. - - The consumer application could run anywhere, such as on a server or a device. - - A consuming application will typically be interested in: - - - distinguishing events such that the exact same event is not processed - twice. - - identifying and selecting the origin context or the producer-assigned - classification. - - identifying the temporal order of the events relative to the originating - context and/or relative to a wall-clock. - - understanding the context-related detail information carried in the event. - - correlating event instances from multiple event producers and send them to - the same consumer context. - - In some cases, the consuming application might be interested in: - - - obtaining further details about the event's subject from the originating - context, like obtaining detail information about a changed object that - requires privileged access authorization. For example, a HR solution might - only publish very limited information in events for privacy reasons, and - any event consumer needing more data will have to obtain details related to - the event from the HR system under their own authorization context. - - interact with the event's subject at the originating context, for instance - reading a storage blob after having been informed that this blob has just - been created. - - Consumer interests motivate requirements for which information producers - ought to include an event. - -3. Middleware routes events from producers to consumers, or onwards to other - middleware. Applications producing events might delegate certain tasks - arising from their consumers' requirements to middleware: +为了鼓励更多人采用 CloudEvents，本仓库将自动收集专有协议和编码。 +本仓库的维护人员不负责创建、维护或通知专有规范的维护人员有关专有规范和CloudEvents规范间的偏差。 + +专有规范将托管在他们自己的仓库或文档站点中，并收集在[专有规范](proprietary-specs.md) +文件中。 专有规范应遵循与核心协议和编码相关的其他规范相同的格式。 + +专有规范将比核心规范受到更少的审查，并且随着 CloudEvents 规范的发展， +相应协议和编码的维护者有责任使规范与 CloudEvents 规范保持同步。 +如果专有规范过时太多，CloudEvents 可能会将指向该规范的链接标记为已弃用或将其删除。 + +如果为同一个协议创建了多个不兼容的规范，存储库维护者将不知道哪个规范是正确的，并列出所有规范的链接。 + +## 现有技术 + +本节介绍了工作组在 CloudEvent 规范开发过程中使用的一些输入材料。 + +### 角色 + +下面列举了可能涉及事件的产生、管理或消费的各种参与者和场景。 + +在这些中，事件生产者和事件消费者的角色是不同的。 +单个应用程序上下文始终可以同时承担多个角色，包括既是事件的生产者又是事件的消费者。 + +1. 应用程序生成供他人使用的事件， + 如为消费者提供有关终端用户活动、状态变化或环境观察的见解， + 或允许通过事件驱动的扩展来补充应用程序的功能。 + + 生产的事件通常与上下文或生产者选择的分类相关。 + 例如，房间中的温度传感器可能被安装位置、房间、楼层和建筑物等上下文限定。 + 运动结果可以按联赛和球队分类。 + + 生产者应用程序可以在任何地方运行，例如在服务器或设备上。 + + 生产的事件可能由生产者或中间人直接提供和发出； + 作为后者的示例，请考虑设备通过负载大小受限的网络（如 LoRaWAN 或 ModBus）传输的事件数据， + 并且符合此规范的事件将由网络网关代表生产者提供。 + + 例如，气象站每 5 分钟通过 LoRaWAN 传输一次 12 字节的专有事件有效载荷用于指示天气状况。 + 然后使用 LoRaWAN 网关以 CloudEvents 格式将事件发布到 Internet 目标。 + LoRaWAN 网关是事件生产者，代表气象站发布事件，并将设置一定的元数据以反映事件的来源(气象站)。 + +2. 应用程序可能以以下目的： + 如显示、存档、分析、工作流处理、监控状态或提供业务解决方案及其基本构建模块的透明化 + 来消费事件。 + + 消费者应用程序可以在任何地方运行，例如在服务器或设备上。 + + 消费应用程序通常对以下内容感兴趣： + + - 区分事件，使得完全相同的事件不会被处理两次。 + - 识别和选择源上下文或生产者指定的分类。 + - 确定事件相对于原始上下文或相对于时钟的时间顺序。 + - 了解事件中携带的上下文相关的详细信息。 + - 关联来自多个事件生产者的事件实例并将它们发送到相同的消费者上下文。 + + 在某些情况下，消费应用程序可能对以下内容感兴趣： + + - 从原始上下文中获取有关事件主题的更多详细信息，例如获取有关需要特权访问授权的已更改对象的详细信息。 + 例如，出于隐私原因，HR 解决方案可能仅在事件中发布非常有限的信息， + 任何需要更多数据的事件消费者都必须在其自己的授权上下文下从 HR 系统获取与事件相关的详细信息 + - 在原始上下文中与事件的主题进行交互，例如在被告知该数据块刚刚创建后读取存储该数据块。 + + 消费者的兴趣激发了信息生产者应该包括事件的需求。 + +3. 中间件将事件从生产者路由到消费者，或转发到其他中间件。 + 产生事件的应用程序可能会将消费者需求产生的某些任务委托给中间件： - Management of many concurrent interested consumers for one of multiple classes or originating contexts of events - - Processing of filter conditions over a class or originating context of - events on behalf of consumers. - - Transcoding, like encoding in MsgPack after decoding from JSON - - Transformation that changes the event's structure, like mapping from a - proprietary format to CloudEvents, while preserving the identity and - semantic integrity of the event. - - Instant "push-style" delivery to interested consumers. - - Storing events for eventual delivery, either for pick-up initiated by the - consumer ("pull") or initiated by the middleware ("push") after a delay. - - Observing event content or event flow for monitoring or diagnostics - purposes. - - To satisfy these needs, middleware will be interested in: - - - A metadata discriminator usable for classification or contextualization of - events so that consumers can express interest in one or multiple such - classes or contexts. For instance, a consumer might be interested in all - events related to a specific directory inside a file storage account. - - A metadata discriminator that allows distinguishing the subject of a - particular event of that class or context. For instance, a consumer might - want to filter out all events related to new files ending with ".jpg" (the - file name being the "new file" event's subject) for the context describing - specific directory inside a file storage account that it has registered - interest on. - - An indicator for the encoding of the event and its data. - - An indicator for the structural layout (schema) for the event and its data. - - Whether its events are available for consumption via a middleware is a - delegation choice of the producer. - - In practice, middleware can take on the role of a - [Producer](spec.md#producer) when it changes the semantic meaning of an - event, a [Consumer](spec.md#consumer) when it takes action based on an event, - or [Intermediary](spec.md#intermediary) when it routes events without making - semantic changes. - -4. Frameworks and other abstractions make interactions with event platform - infrastructure simpler, and often provide common API surface areas for - multiple event platform infrastructures. - - Frameworks are often used for turning events into an object graph, and to - dispatch the event to some specific handling user-code or user-rule that - permits the consuming application to react to a particular kind of occurrence - in the originating context and on a particular subject. - - Frameworks are most interested in semantic metadata commonality across the - platforms they abstract, so that similar activities can be handled uniformly. - - For a sports application, a developer using the framework might be interested - in all events from today's game (subject) of a team in a league (topic of - interest) but wanting to handle reports of "goal" differently than reports of - "substitution". For this, the framework will need a suitable metadata - discriminator that frees it from having to understand the event details. - -### Value Proposition - -This section describes some of the use-cases that explain the value of -CloudEvents. - -#### Normalizing Events Across Services & Platforms - -Major event publishers (e.g. AWS, Microsoft, Google, etc.) all publish events in -different formats on their respective platforms. There are even a few cases -where services on the same provider publish events in different formats (e.g. -AWS). This forces event consumers to implement custom logic to read or munge -event data across platforms and occasionally across services on a single -platform. - -CloudEvents can offer a single experience for authoring consumers that handle -events across all platforms and services. - -#### Facilitating Integrations Across Services & Platforms - -Event data being transported across environments is increasingly common. -However, without a common way of describing events, delivery of events across -environments is hindered. There is no single way of determining where an event -came from and where it might be going. This prevents tooling to facilitate -successful event delivery and consumers from knowing what to do with event data. - -CloudEvents offers useful metadata which middleware and consumers can rely upon -to facilitate event routing, logging, delivery and receipt. - -#### Increasing Portability of Functions-as-a-Service - -Functions-as-a-Service (also known as serverless computing) is one of the -fastest growing trends in IT and it is largely event-driven. However, a primary -concern of FaaS is vendor lock-in. This lock-in is partially caused by -differences in function APIs and signatures across providers, but the lock-in is -also caused by differences in the format of event data received within -functions. - -CloudEvents' common way of describing event data increases the portability of -Functions-as-a-Service. - -#### Improving Development & Testing of Event-Driven/Serverless Architectures - -The lack of a common event format complicates development and testing of -event-driven and serverless architectures. There is no easy way to mock events -accurately for development and testing purposes, and help emulate event-driven -workflows in a development environment. - -CloudEvents can enable better developer tools for building, testing and handling -the end-to-end lifecycle of event-driven and serverless architectures. + - 代表消费者在类或事件的原始上下文上处理过滤条件。 + - 转码，比如从 JSON 解码后在 MsgPack 中编码 + - 更改事件结构的转换，例如从专有格式映射到 CloudEvents，同时保留事件的身份和语义完整性。 + - 即时“推送式”传输给感兴趣的消费者。 + - 存储最终传输的事件，用于由消费者发起的“拉”请求，或延迟后由中间件发起“推”请求。 + - 观察事件内容或事件流以进行监控或诊断。 + + 为了满足这些需求，中间件将对以下方面感兴趣： + + - 一种元数据鉴别器，可用于事件的分类或上下文化，以便消费者可以表达对一个或多个类或上下文的兴趣。 + 例如，消费者可能对文件存储帐户内的特定目录相关的所有事件感兴趣。 + - 一种元数据鉴别器，允许区分该类或上下文的特定事件的主题。例如，消费者可能希望过滤掉与以“.jpg”结尾的 + 新文件相关的所有事件（文件名是“新文件”事件的主题）， + 用于描述其已注册的文件存储帐户内的特定目录的上下文兴趣。 + - 一个事件及其数据编码的指示器。 + - 一个事件及其数据的结构布局（模式）的指示器。 + + 事件是否可通过中间件消费取决于生产者的选择。 -#### Event Data Evolution + 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec.md#producer)的角色， + 当它根据事件采取行动时可以扮演[消费者](spec.md#consumer)的角色， + 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec.md#intermediary)的角色。 + +4. 框架和其他抽象使与事件平台基础设施的交互更简单， + 并且通常为多个事件平台基础设施提供公共 API 区域。 -Most platforms and services version the data model of their events differently -(if they do this at all). This creates an inconsistent experience for publishing -and consuming the data model of events as those data models evolve. + 框架通常用于将事件转换为对象图，并将事件分派给某些特定的处理用户代码或用户规则， + 这些用户代码或用户规则允许消费应用程序对原始上下文和特定主题中的特定类型的事件做出反应。 -CloudEvents can offer a common way to version and evolve event data. This will -help event publishers safely version their data models based on best practices, -and this help event consumers safely work with event data as it evolves. + 框架最感兴趣的是跨它们抽象的平台的语义元数据通用性，以便可以统一处理类似的活动。 -#### Normalizing Webhooks + 对于体育应用程序，使用该框架的开发人员可能对联盟中一支球队今天的比赛（主题） + 的所有事件感兴趣，但希望以不同于“换人”事件的方式处理“得分”事件。 + 为此，框架将需要一个合适的元数据鉴别器，使其不必了解事件细节。 -Webhooks is a style of event publishing which does not use a common format. -Consumers of webhooks don’t have a consistent way to develop, test, identify, -validate, and overall process event data delivered via webhooks. +### 价值主张 -CloudEvents can offer consistency in webhook publishing and consumption. +本节介绍了一些能够展示 CloudEvents 价值主张的用例。 -#### Policy Enforcement +#### 跨服务和平台规范化事件 -The transiting of events between systems may need to be filtered, transformed, -or blocked due to security and policy concerns. Examples may be to prevent -ingress or egress of the events such as event data containing sensitive -information or wanting to disallow the information flow between the sender and -receiver. +主要事件发布者（例如 AWS、Microsoft、Google 等）都在各自的平台上以不同的格式发布事件。 +甚至在少数情况下，同一提供商的服务以不同格式（例如 AWS）发布事件。 +这迫使事件消费者实现自定义逻辑以跨平台读取或处理事件数据，有时甚至需要跨单个平台的多个服务处理。 -A common event format would allow easier reasoning about the data being -transited and allow for better introspection of the data. +CloudEvents 可以为那些跨平台和服务处理事件的使用者提供单一体验。 -#### Event Tracing +#### 促进跨服务和平台的集成 -An event sent from a source may result in a sequence of additional events sent -from various middleware devices such as event brokers and gateways. CloudEvents -includes metadata in events to associate these events as being part of an event -sequence for the purpose of event tracing and troubleshooting. +跨环境传输的事件数据越来越普遍。 +然而，如果没有描述事件的通用方式，跨环境的事件传递就会受到阻碍。 +CloudEvents之前没有单一的方法可以确定事件的来源和可能的去向。 +这对研究成功传输事件事件工具和消费者知道如何处理事件数据形成了巨大阻碍。 + +CloudEvents 提供有用的元数据，中间件和消费者可以依赖这些元数据来促进事件路由、日志记录、传输和接收。 + +#### 提高功能即服务的可移植性 + +功能即服务（也称为serverless计算）是 IT 中增长最快的趋势之一，它主要是由事件驱动的。 +然而，FaaS 的一个主要问题是供应商锁定。 +这种锁定部分是由函数 API 和供应商之间签名的差异引起的， +锁定同样也是由函数内接收的事件数据格式的差异引起的。 + +CloudEvents提供描述事件数据的通用方式提高了功能即服务的可移植性。 + +#### 改进事件驱动/serverless架构的开发和测试 + +缺乏通用事件格式使事件驱动和serverless架构的开发和测试变得复杂。 +没有简单的方法可以准确地为开发和测试目的模拟事件，并帮助在开发环境中模拟事件驱动的工作流。 + +CloudEvents 可以提供更好的开发工具来构建、测试和处理事件驱动和无服务器架构的端到端生命周期。 + +#### 事件数据发展 + +大多数平台和服务对其事件的数据模型进行不同的版本控制（如果他们这样做的话）。 +随着这些数据模型的发展，这会为发布和使用事件的数据模型带来不一致的体验。 + +CloudEvents 可以提供一种通用的方式来版本化和发展事件数据。 +这将帮助事件发布者根据最佳实践安全地对其数据模型进行版本控制， +并且这有助于事件消费者随着事件数据的发展安全地使用它。 + +#### 规范化 Webhook + +Webhooks 是一种不使用通用格式的来发布事件的模式。 +Webhook 的使用者没有一致的方式来开发、测试、识别、验证和整体处理通过 Webhook 传输的事件数据。 + +CloudEvents 可以提供 Webhook 发布和消费事件的一致性。 + +#### 安全策略 + +出于安全和策略考虑，可能需要过滤、转换或阻止系统之间的事件传输。 +比如可能需要防止事件的进入或退出，如包含敏感信息的事件数据或想要禁止发送方和接收方之间的信息流。 + +通用事件格式将允许更容易地推理正在传输的数据，并提供更好的数据自查。 + +#### 事件追踪 + +从源发送的事件可能会出现在一系列附加事件之间， +这些附加事件从各种中间件设备（例如事件代理和网关）发出的。 +CloudEvents 在事件中包含元数据以将这些事件关联为事件序列的一部分，以便进行事件跟踪和故障排除。 #### IoT -IoT devices send and receive events related to their functionality. For example, -a connected thermostat will send telemetry on the current temperature and could -receive events to change temperatures. These devices typically have a -constrained operating environment (cpu, memory) requiring a well-defined event -message format. In a lot of cases these messages are binary encoded instead of -textual. Whether directly from the device or transformed via a gateway, -CloudEvents would allow for a better description of the origin of the message -and the format of the data contained within the message. - -#### Event Correlation - -A serverless application/workflow could be associated with multiple events from -different event sources/producers. For example, a burglary detection -application/workflow could involve both a motion event and a door/window open -event. A serverless platform could receive many instances of each type of -events, e.g. it could receive motion events and window open events from -different houses. - -The serverless platform needs to correlate one type of event instance correctly -with other types of event instances and map a received event instance to the -correct application/workflow instance. CloudEvents will provide a standard way -for any event consumer (e.g. the serverless platform) to locate the event -correlation information/token in the event data and map a received event -instance to the correct application/workflow instance. - -### Existing Event Formats - -As with the previous section, the examination (and understanding) of the current -state of the world was very important to the group. To that end, a sampling of -existing current event formats that are used in practice today was gathered. +物联网设备会发送和接收与其功能相关的事件。 +例如，连接的恒温器将发送有关当前温度的遥测数据， +并可以接收改变温度的事件。 +这些设备通常具有受限的操作环境（cpu、内存），需要明确定义的事件消息格式。 +在很多情况下，这些消息是二进制编码的，而不是文本的。 +无论是直接来自设备还是通过网关转换，CloudEvents 都可以更好地描述消息的来源和消息中包含的数据格式。 + +#### 事件关联 + +一个serverless应用或工作流可能与来自不同事件源或事件生产者的多个事件相关联。 +例如，盗窃检测应用程序/工作流可能涉及运动事件和门/窗打开事件。 +一个serverless平台可能接收每种类型事件的许多实例，例如 它可以接收来自不同房屋的运动事件和开窗事件。 + +serverless平台需要将一种类型的事件实例与其他类型的事件实例正确关联， +并将接收到的事件实例映射到正确的应用/工作流实例。 +CloudEvents 将为任何事件使用者（例如serverless平台）提供一种标准方式， +以在事件数据中定位事件关联信息/令牌并将接收到的事件实例映射到正确的应用/工作流实例。 + +### 现有的数据格式 + +与上一节一样，对当前现状的调查（和理解）对CloudEvents 小组来说非常重要。 +为此，下面列出了在实践中被广泛使用的当前事件格式的样本。 #### Microsoft - Event Grid @@ -661,8 +584,7 @@ existing current event formats that are used in practice today was gathered. #### AWS - CloudWatch Events -A high proportion of event-processing systems on AWS are converging on the use -of this format. +AWS 上的很大一部分事件处理系统都在使用这种格式。 ``` { From 9ab0c3d11ca2acae084eefdffcde45620ac39d27 Mon Sep 17 00:00:00 2001 From: JieDing Date: Mon, 8 Nov 2021 17:24:14 +0800 Subject: [PATCH 37/60] Update primer.md Signed-off-by: JieDing --- primer.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/primer.md b/primer.md index 9681d2a84..08a69951f 100644 --- a/primer.md +++ b/primer.md @@ -12,16 +12,16 @@ - [CloudEvents 概念](#CloudEvents-概念) - [设计目标](#设计目标) - [架构](#架构) -- [属性版本](#属性版本) +- [属性版本控制](#属性版本控制) - [CloudEvent 属性](#CloudEvent-属性) - [CloudEvent 属性扩展](#CloudEvent-属性扩展) - [生产 CloudEvents](#生产CloudEvents) - [合格的协议与编码](#合格的协议与编码) -- [Proprietary 协议和编码](#专有的协议与编码) -- [Prior Art](#现有技术) -- [Roles](#角色) -- [Value Proposition](#价值主张) -- [Existing Event Formats](#existing-event-formats) +- [专有的协议和编码](#专有的协议与编码) +- [现有技术](#现有技术) +- [角色](#角色) +- [价值主张](#价值主张) +- [现有的数据格式](#现有的数据格式) ## 历史 @@ -152,7 +152,7 @@ CloudEvents 规范在很大程度上并未规定与 CloudEvents 的创建或处 因此，如果在处理 CloudEvent 过程中出现错误， 请使用正常的协议级错误处理机制进行处理。 -## 属性版本 +## 属性版本控制 对于某些 CloudEvents 属性，由其值引用的实体或数据模型可能会随时间变化。 例如，`dataschema`可能引用模式文档的一个特定版本。 From 783c814c100b02e563a5e9f5fc2bafb088d30a8a Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 14:24:47 +0800 Subject: [PATCH 38/60] Update spec.md Signed-off-by: JieDing --- spec.md | 854 +++++++++++++++++++++++++------------------------------- 1 file changed, 385 insertions(+), 469 deletions(-) diff --git a/spec.md b/spec.md index 5d3899541..1f1428ec8 100644 --- a/spec.md +++ b/spec.md @@ -1,547 +1,463 @@ -# CloudEvents - Version 1.0 +# CloudEvents 核心规范- 1.0 版本 -## Abstract +## 摘要 +CloudEvents 是一个用于定义事件格式的供应商中立规范。 CloudEvents is a vendor-neutral specification for defining the format of event data. -## Table of Contents +## 目录 -- [Overview](#overview) -- [Notations and Terminology](#notations-and-terminology) -- [Context Attributes](#context-attributes) -- [Event Data](#event-data) -- [Size Limits](#size-limits) -- [Privacy & Security](#privacy-and-security) -- [Example](#example) +- [概览](#概览) +- [符号和术语](#符号和术语) +- [上下文属性](#上下文属性) +- [事件数据](#事件数据) +- [大小限制](#大小限制) +- [隐私与安全](#隐私与安全) +- [示例](#示例) -## Overview +## 概览 -Events are everywhere. However, event producers tend to describe events -differently. +事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 -The lack of a common way of describing events means developers are constantly -re-learning how to consume events. This also limits the potential for libraries, -tooling and infrastructure to aid the delivery of event data across -environments, like SDKs, event routers or tracing systems. The portability and -productivity that can be achieved from event data is hindered overall. +对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。 +它同样限制了那些用来帮助事件数据完成 跨环境传输的库(如SDKs)， +工具(如事件路由器)和基础设施(如事件追踪系统)的发展。 +总体来看，这种匮乏严重阻碍了事件数据的可移植性和生产力。 -CloudEvents is a specification for describing event data in common formats to -provide interoperability across services, platforms and systems. +CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 -Event Formats specify how to serialize a CloudEvent with certain encoding -formats. Compliant CloudEvents implementations that support those encodings MUST -adhere to the encoding rules specified in the respective event format. All -implementations MUST support the [JSON format](json-format.md). +事件格式指定如何使用某些编码格式序列化一个 CloudEvent。 +支持那些编码且兼容 CloudEvents 的实现必须遵守相应事件格式中指定的编码规则。 +所有实现都必须支持 [JSON 格式](json-format.md)。 -For more information on the history, development and design rationale behind the -specification, see the [CloudEvents Primer](primer.md) document. +有关规范背后的历史、开发和设计原理等更多信息， +请参阅 CloudEvents [入门文档](primer.md)。 -## Notations and Terminology +## 符号和术语 -### Notational Conventions +### 符号约定 -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). +本文档中的关键词 +"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 需要按照 +[RFC 2119](https://tools.ietf.org/html/rfc2119) 中的描述来理解。 -For clarity, when a feature is marked as "OPTIONAL" this means that it is -OPTIONAL for both the [Producer](#producer) and [Consumer](#consumer) of a -message to support that feature. In other words, a producer can choose to -include that feature in a message if it wants, and a consumer can choose to -support that feature if it wants. A consumer that does not support that feature -will then silently ignore that part of the message. The producer needs to be -prepared for the situation where a consumer ignores that feature. An -[Intermediary](#intermediary) SHOULD forward OPTIONAL attributes. +为清楚起见， +当一个功能被标记为“OPTIONAL”时，这意味着消息的 +[生产者](#生产者)和[消费者](#消费者) 都可以自行选择是否支持该功能。 +换句话说，生产者可以在需要时在消息中包含该功能，消费者也可以在需要时选择支持该功能。 +不支持该功能的消费者将默默地忽略该部分消息。 +生产者需要做好消费者并没有启用该功能的准备。 +[中间人](#中间人) 应当转发OPTIONAL属性。 -### Terminology +### 术语 -This specification defines the following terms: +本规范定义了下列术语 -#### Occurrence +#### 发生 -An "occurrence" is the capture of a statement of fact during the operation of a -software system. This might occur because of a signal raised by the system or a -signal being observed by the system, because of a state change, because of a -timer elapsing, or any other noteworthy activity. For example, a device might go -into an alert state because the battery is low, or a virtual machine is about to -perform a scheduled reboot. +“发生”是指在软件系统运行期间对事实状态的捕获。 +这可能是由于系统发出了信号或系统观察到信号、状态更改、计时器超时 +或任何其他值得注意的活动而发生的。 +例如，设备可能会因为电池电量低或虚拟机即将执行计划的重启而进入警报状态。 -#### Event +#### 事件 -An "event" is a data record expressing an occurrence and its context. Events are -routed from an event producer (the source) to interested event consumers. The -routing can be performed based on information contained in the event, but an -event will not identify a specific routing destination. Events will contain two -types of information: the [Event Data](#event-data) representing the Occurrence -and [Context](#context) metadata providing contextual information about the -Occurrence. A single occurrence MAY result in more than one event. +“事件”是表示"发生"及其上下文的数据记录。 +事件从事件生产者（源）路由到对它感兴趣的事件消费者。 +事件中包含的信息帮助完成路由操作，但事件不会标识特定的路由目的地。 +事件将包含两种类型的信息：表示"发生"的 [事件数据](#事件数据) +和提供有关事件的环境信息的[上下文](#上下文) 元数据。 +一次"发生"可能导致多个事件的产生。 -#### Producer +#### 生产者 -The "producer" is a specific instance, process or device that creates the data -structure describing the CloudEvent. +“生产者”是一种特定的实例、进程或设备，它能够创建用来描述CloudEvent的数据结构。 -#### Source +#### 源 -The "source" is the context in which the occurrence happened. In a distributed -system it might consist of multiple [Producers](#producer). If a source is not -aware of CloudEvents, an external producer creates the CloudEvent on behalf of -the source. +"源"是事件发生的上下文环境。在分布式系统中，它可能由多个生产者组成。 +如果一个源无法查看到CloudEvents，那么一定有有外部的生产者在代替源来生产CloudEvent。 -#### Consumer +#### 消费者 -A "consumer" receives the event and acts upon it. It uses the context and data -to execute some logic, which might lead to the occurrence of new events. +一个“消费者”会接收事件并根据事件采取一定的行为。 +它使用上下文环境和事件数据来执行一些逻辑，这可能会导致新事件的发生。 -#### Intermediary +#### 中间人 -An "intermediary" receives a message containing an event for the purpose of -forwarding it to the next receiver, which might be another intermediary or a -[Consumer](#consumer). A typical task for an intermediary is to route the event -to receivers based on the information in the [Context](#context). +一个“中间人”会接收包含事件的消息， +并将其转发给下一个接收者，但该接收者可能是另一个中间人或事件[消费者](#消费者)。 +中间人的典型任务就是根据[上下文](#context)环境中的信息将事件路由到接收者。 -#### Context +#### 上下文 -Context metadata will be encapsulated in the -[Context Attributes](#context-attributes). Tools and application code can use -this information to identify the relationship of Events to aspects of the system -or to other Events. - -#### Data - -Domain-specific information about the occurrence (i.e. the payload). This might -include information about the occurrence, details about the data that was -changed, or more. See the [Event Data](#event-data) section for more -information. +上下文环境元数据被封装在[上下文-属性](#上下文-属性)中。 +工具和应用程序代码可以使用此信息来识别事件与系统方面或事件与其他事件的关系。 -#### Event Format - -An Event Format specifies how to serialize a CloudEvent as a sequence of bytes. -Stand-alone event formats, such as the [JSON format](json-format.md), specify -serialization independent of any protocol or storage medium. Protocol Bindings -MAY define formats that are dependent on the protocol. - -#### Message - -Events are transported from a source to a destination via messages. - -A "structured-mode message" is one where the event is fully encoded using -a stand-alone event format and stored in the message body. - -A "binary-mode message" is one where the event data is stored in the message -body, and event attributes are stored as part of message meta-data. - -#### Protocol - -Messages can be delivered through various industry standard protocol (e.g. HTTP, -AMQP, MQTT, SMTP), open-source protocols (e.g. Kafka, NATS), or platform/vendor -specific protocols (AWS Kinesis, Azure Event Grid). - -#### Protocol Binding - -A protocol binding describes how events are sent and received over a given -protocol, in particular how events are mapped to messages in that protocol. - -## Context Attributes - -Every CloudEvent conforming to this specification MUST include context -attributes designated as REQUIRED, MAY include one or more OPTIONAL context -attributes and MAY include one or more extension attributes. - -These attributes, while descriptive of the event, are designed such that they -can be serialized independent of the event data. This allows for them to be -inspected at the destination without having to deserialize the event data. +#### 数据 -### Attribute Naming Convention - -The CloudEvents specifications define mappings to various protocols and -encodings, and the accompanying CloudEvents SDK targets various runtimes and -languages. Some of these treat metadata elements as case-sensitive while others -do not, and a single CloudEvent might be routed via multiple hops that involve a -mix of protocols, encodings, and runtimes. Therefore, this specification limits -the available character set of all attributes such that case-sensitivity issues -or clashes with the permissible character set for identifiers in common -languages are prevented. - -CloudEvents attribute names MUST consist of lower-case letters ('a' to 'z') or -digits ('0' to '9') from the ASCII character set. Attribute names SHOULD be -descriptive and terse and SHOULD NOT exceed 20 characters in length. - -### Type System - -The following abstract data types are available for use in attributes. Each of -these types MAY be represented differently by different event formats and in -protocol metadata fields. This specification defines a canonical -string-encoding for each type that MUST be supported by all implementations. - -- `Boolean` - a boolean value of "true" or "false". - - String encoding: a case-sensitive value of `true` or `false`. -- `Integer` - A whole number in the range -2,147,483,648 to +2,147,483,647 - inclusive. This is the range of a signed, 32-bit, twos-complement encoding. - Event formats do not have to use this encoding, but they MUST only use - `Integer` values in this range. - - String encoding: Integer portion of the JSON Number per - [RFC 7159, Section 6](https://tools.ietf.org/html/rfc7159#section-6) -- `String` - Sequence of allowable Unicode characters. The following characters - are disallowed: - - the "control characters" in the ranges U+0000-U+001F and U+007F-U+009F (both - ranges inclusive), since most have no agreed-on meaning, and some, such as - U+000A (newline), are not usable in contexts such as HTTP headers. - - code points - [identified as noncharacters by Unicode](http://www.unicode.org/faq/private_use.html#noncharacters). - - code points identifying Surrogates, U+D800-U+DBFF and U+DC00-U+DFFF, both - ranges inclusive, unless used properly in pairs. Thus (in JSON notation) - "\uDEAD" is invalid because it is an unpaired surrogate, while - "\uD800\uDEAD" would be legal. -- `Binary` - Sequence of bytes. - - String encoding: Base64 encoding per - [RFC4648](https://tools.ietf.org/html/rfc4648). -- `URI` - Absolute uniform resource identifier. - - String encoding: `Absolute URI` as defined in - [RFC 3986 Section 4.3](https://tools.ietf.org/html/rfc3986#section-4.3). -- `URI-reference` - Uniform resource identifier reference. - - String encoding: `URI-reference` as defined in - [RFC 3986 Section 4.1](https://tools.ietf.org/html/rfc3986#section-4.1). -- `Timestamp` - Date and time expression using the Gregorian Calendar. - - String encoding: [RFC 3339](https://tools.ietf.org/html/rfc3339). - -All context attribute values MUST be of one of the types listed above. -Attribute values MAY be presented as native types or canonical strings. - -A strongly-typed programming model that represents a CloudEvent or any extension -MUST be able to convert from and to the canonical string-encoding to the -runtime/language native type that best corresponds to the abstract type. - -For example, the `time` attribute might be represented by the language's native -_datetime_ type in a given implementation, but it MUST be settable providing an -RFC3339 string, and it MUST be convertible to an RFC3339 string when mapped to a -header of an HTTP message. - -A CloudEvents protocol binding or event format implementation MUST likewise be -able to convert from and to the canonical string-encoding to the corresponding -data type in the encoding or in protocol metadata fields. - -An attribute value of type `Timestamp` might indeed be routed as a string -through multiple hops and only materialize as a native runtime/language type at -the producer and ultimate consumer. The `Timestamp` might also be routed as a -native protocol type and might be mapped to/from the respective -language/runtime types at the producer and consumer ends, and never materialize -as a string. - -The choice of serialization mechanism will determine how the context attributes -and the event data will be serialized. For example, in the case of a JSON -serialization, the context attributes and the event data might both appear -within the same JSON object. - -### REQUIRED Attributes - -The following attributes are REQUIRED to be present in all CloudEvents: +关于事件的特定域信息（即有效负载）。这可能包括有关事件的信息、有关已更改数据的详细信息等。 +有关更多信息，请参阅[事件数据](#事件数据)部分。 + +#### 事件格式 + +一个事件格式会指定如何将 CloudEvent 序列化为字节序列。 +独立事件格式（例如 [JSON 格式](json-format.md)）指定独立于任何协议或存储介质的序列化。 +协议绑定可以定义依赖于协议的格式。 + +#### 消息 + +事件通过消息从源传输到目标。 + +“结构化模式消息”是一种使用独立事件格式对事件进行完全编码并存储在消息体中的消息。 + +“二进制模式消息”是将事件数据存储在消息体中，并将事件属性作为消息元数据的一部分存储下来。 + +#### 协议 + +消息可以通过各种行业标准协议 +（例如 HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或平台/供应商 +专有协议（AWS Kinesis、Azure 事件网格）传输。 + +#### 协议绑定 + +协议绑定描述了如何通过给定协议发送和接收事件，特别是如何将事件映射到该协议的消息中去。 + +## 上下文属性 + +每个符合本规范的 CloudEvent 必须包括指定为 REQUIRED 的上下文属性， +可以包括一个或多个OPTIONAL上下文属性， +并且可以包括一个或多个扩展属性。 + +这些属性虽然描述了事件，但被设计为可以独立于事件数据进行序列化。 +这允许在不反序列化事件数据的情况下，在目的检查这些上下文属性。 + +### 属性命名约定 + +CloudEvents 规范定义了到各种协议和编码的映射，随附的 CloudEvents SDK 面向各种运行时和语言。 +其中一些将元数据元素区分大小写，而另一些则不区分， +并且单个 CloudEvent 可能通过涉及到协议、编码和运行时混合的多个跃点进行路由。 +因此，本规范限制了所有属性的可用字符集，以防止区分大小写问题或与通用语言中标识符的合法字符集冲突问题。 + +CloudEvents 属性名称必须由来自 ASCII 字符集的小写字母（“a”到“z”）或数字（“0”到“9”）组成。 +属性名称应该是描述性的和简洁的，并且长度不应超过 20 个字符。 + +### 类型系统 + +以下抽象数据类型可用于属性。 +这些类型中的每一种都可以由不同的事件格式和协议元数据字段以不同的方式表示。 +本规范为所有实现必须支持的每种类型定义了规范的字符串编码。 + +- `Boolean` - “true”或“false”的布尔值。 + - 字符串编码：区分大小写的`true` 或 `false`值。 +- `Integer` -范围在 -2,147,483,648 到 +2,147,483,647 （包含）之间的整数。 + 这是有符号 32 位二进制补码编码的范围。 + 事件格式不必使用此编码，但它们必须使用在此范围内的`Integer` 值。 + - 字符串编码: 符合 + [RFC 7159, 第 6 节](https://tools.ietf.org/html/rfc7159#section-6) + JSON 数字的整数部分 +- `String` - 允许的 Unicode 字符序列。 不允许使用以下字符： + - 范围 U+0000-U+001F 和 U+007F-U+009F（包含首尾）中的“控制字符”， + 因为大多数没有商定的含义，还有一些，例如 U+000A（换行符）， 在如 HTTP 头部之类的上下文中不可用。 + -[被 Unicode 标识为非字符的](http://www.unicode.org/faq/private_use.html#noncharacters) + 代码点。 + - 被 Unicode 标识为代理项的代码点, 范围 U+D800-U+DBFF 和 U+DC00-U+DFFF（包含首尾） + , 除非被合理的用作代理对. 因此（在 JSON 符号中） + “\uDEAD”是无效的，因为它是一个未配对的代理，而“\uD800\uDEAD”是合法的。 +- `Binary` - 字节序列. + - 字符串编码: 基于 + [RFC4648](https://tools.ietf.org/html/rfc4648) 的Base64 编码。 +- `URI` - 绝对统一资源标识符。 + - 字符串编码: + [RFC 3986 第 4.3 节](https://tools.ietf.org/html/rfc3986#section-4.3) + 中定义的 `Absolute URI` 。 +- `URI-reference` - 统一资源标识符引用。 + - 字符串编码: + [RFC 3986 第 4.1 节](https://tools.ietf.org/html/rfc3986#section-4.1) + 中定义的`URI-reference` 。 +- `Timestamp` - 使用公历的日期和时间表达式。 + - 字符串编码: [RFC 3339](https://tools.ietf.org/html/rfc3339) 。 + +所有上下文属性值必须是上面列出的类型之一。 +属性值可以表示为原生类型或规范字符串。 + +当强类型编程语言表示 CloudEvent 或任何扩展时， +必须能够在规范字符串编码与对应抽象类型的运行时/编程语言类型之间进行转换。 + +例如，在给定的实现中，`time` 属性可能由编程语言的本地时间类型表示， +但它必须是可设置提供 RFC3339 字符串的， +并且当映射到 HTTP 消息头时，它必须可转换为 RFC3339 字符串。 + +CloudEvents 协议绑定或事件格式实现同样必须能够 +在规范字符串编码与协议元数据字段中的对应数据类型之间进行转换。 + +`Timestamp` 类型的属性值确实可能以字符串形式路由通过多个跃点， +并且仅在生产者和最终消费者处实现为本地运行时/语言类型。 +`Timestamp` 类型也可以作为本机协议类型路由， +并且可以在生产者和消费者端映射到/从各自的语言/运行时类型，但永远不会转为字符串格式。 + +序列化机制的选择将决定上下文属性和事件数据将如何序列化。 +例如，在 JSON 序列化的情况下，上下文属性和事件数据可能都出现在同一个 JSON 对象中。 + +### 必要属性 + +下列属性必须自所有的 CloudEvents 中展示： #### id -- Type: `String` -- Description: Identifies the event. Producers MUST ensure that `source` + `id` - is unique for each distinct event. If a duplicate event is re-sent (e.g. due - to a network error) it MAY have the same `id`. Consumers MAY assume that - Events with identical `source` and `id` are duplicates. -- Examples: - - An event counter maintained by the producer - - A UUID -- Constraints: - - REQUIRED - - MUST be a non-empty string - - MUST be unique within the scope of the producer +- 类型: `String` +- 描述: 标识一个事件。 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 + 如果重复的事件被重新发送（例如由于网络错误），它可能具有相同的 `id`。 + Consumers MAY assume that + 消费者可以假设具有相同`source` 和 `id`的事件是重复的。 +- 示例: + - 一个由生产者维护的事件计数器 + - 一个 UUID +- 约束条件: + - 必要的 + - 必须是非空字符串 + - 在生产者的范围内必须是唯一的 #### source -- Type: `URI-reference` -- Description: Identifies the context in which an event happened. Often this - will include information such as the type of the event source, the - organization publishing the event or the process that produced the event. The - exact syntax and semantics behind the data encoded in the URI is defined by - the event producer. - - Producers MUST ensure that `source` + `id` is unique for each distinct event. - - An application MAY assign a unique `source` to each distinct producer, which - makes it easy to produce unique IDs since no other producer will have the same - source. The application MAY use UUIDs, URNs, DNS authorities or an - application-specific scheme to create unique `source` identifiers. - - A source MAY include more than one producer. In that case the producers MUST - collaborate to ensure that `source` + `id` is unique for each distinct event. - -- Constraints: - - REQUIRED - - MUST be a non-empty URI-reference - - An absolute URI is RECOMMENDED -- Examples - - Internet-wide unique URI with a DNS authority. +- 类型: `URI-reference` +- 描述: 标识事件发生的上下文背景。 这通常包括诸如事件源类型、发布事件的组织 + 或产生事件的过程等信息。URI 中编码的数据背后的确切语法和语义由事件生产者定义。 + + 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 + + 应用程序可以为每个不同的生产者分配一个唯一的`source`， + 这使得生成唯一 ID 变得容易，因为没有其他生产者将拥有相同的来源。 + 应用程序可以使用 UUIDs、URNs、DNS权威机构或特定于应用程序的方案来创建唯一的`source` 标识符。 + + 一个来源可以包括多个生产者。 + 在这种情况下，生产者必须协作以确保每个不同事件的 `source` + `id`都是唯一的。 + +- 约束条件: + - 必要的 + - 必须是非空 URI-reference + - 推荐使用 绝对 URI +- 示例 + - 具有 DNS 权限的 Internet 范围唯一 URI： - https://github.com/cloudevents - mailto:cncf-wg-serverless@lists.cncf.io - - Universally-unique URN with a UUID: + - 具有 UUID 的通用唯一 URN： - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 - - Application-specific identifiers + - 应用程序专有的标识符 - /cloudevents/spec/pull/123 - /sensors/tn-1234567/alerts - 1-555-123-4567 #### specversion -- Type: `String` -- Description: The version of the CloudEvents specification which the event - uses. This enables the interpretation of the context. Compliant event - producers MUST use a value of `1.0` when referring to this version of the - specification. -- Constraints: - - REQUIRED - - MUST be a non-empty string +- 类型: `String` +- 描述: 事件使用的 CloudEvents 规范的版本。 + 这让解释上下文环境更容易。 + 当引用这个版本的规范时，兼容的事件生产者必须使用 `1.0` 的值。 +- 约束条件: + - 必要的 + - 必须是非空字符串 #### type -- Type: `String` -- Description: This attribute contains a value describing the type of event - related to the originating occurrence. Often this attribute is used for - routing, observability, policy enforcement, etc. The format of this is - producer defined and might include information such as the version of the - `type` - see - [Versioning of Attributes in the Primer](primer.md#versioning-of-attributes) - for more information. -- Constraints: - - REQUIRED - - MUST be a non-empty string - - SHOULD be prefixed with a reverse-DNS name. The prefixed domain dictates the - organization which defines the semantics of this event type. -- Examples +- 类型: `String` +- 描述: 该属性包含一个值，描述与原始事件相关的事件类型。 + 该属性通常用于路由、可观察性、策略实施等。其格式是生产者定义的，可能包括诸如 `type`版本之类的信息 + -从 + [入门文档-属性版本控制](primer.md#属性版本控制) 中获得更多信息 + +- 约束条件: + - 必要的 + - 必须是非空字符串 + - 应该以反向 DNS 名称作为前缀。该前缀域表明了定义此事件类型语义的组织。 +- 示例 - com.github.pull.create - com.example.object.delete.v2 -### OPTIONAL Attributes +### 可选属性 -The following attributes are OPTIONAL to appear in CloudEvents. See the -[Notational Conventions](#notational-conventions) section for more information -on the definition of OPTIONAL. +下列属性在 CloudEvents 中是可选的. 在 +[符号约定](#notational-conventions) 中查看更多 OPTIONAL 定义的信息。 #### datacontenttype -- Type: `String` per [RFC 2046](https://tools.ietf.org/html/rfc2046) -- Description: Content type of `data` value. This attribute enables `data` to - carry any type of content, whereby format and encoding might differ from that - of the chosen event format. For example, an event rendered using the - [JSON envelope](./json-format.md#3-envelope) format might carry an XML payload - in `data`, and the consumer is informed by this attribute being set to - "application/xml". The rules for how `data` content is rendered for different - `datacontenttype` values are defined in the event format specifications; for - example, the JSON event format defines the relationship in - [section 3.1](./json-format.md#31-handling-of-data). - - For some binary mode protocol bindings, this field is directly mapped to the - respective protocol's content-type metadata property. Normative rules for the - binary mode and the content-type metadata mapping can be found in the - respective protocol - - In some event formats the `datacontenttype` attribute MAY be omitted. For - example, if a JSON format event has no `datacontenttype` attribute, then it is - implied that the `data` is a JSON value conforming to the "application/json" - media type. In other words: a JSON-format event with no `datacontenttype` is - exactly equivalent to one with `datacontenttype="application/json"`. - - When translating an event message with no `datacontenttype` attribute to a - different format or protocol binding, the target `datacontenttype` SHOULD be - set explicitly to the implied `datacontenttype` of the source. - -- Constraints: - - OPTIONAL - - If present, MUST adhere to the format specified in - [RFC 2046](https://tools.ietf.org/html/rfc2046) -- For Media Type examples see +- 类型: `String` [RFC 2046](https://tools.ietf.org/html/rfc2046) +- 描述: `data`值的内容类型。 此属性使`data`能够承载任何类型的内容， + 因此格式和编码可能与所选事件格式的不同。 + 例如，使用 [JSON envelope](./json-format.md#3-envelope) + 格式呈现的事件可能在数据中携带 XML 的payload，这个属性可以用来通知消费者 + 设置"application/xml"。 + 关于`data`内容如何提供不同的`datacontenttype`的值的规则在事件格式规范中定义。 + 例如，JSON 事件格式定义了 [3.1 节](./json-format.md#31-handling-of-data)中的关系。 + 对于某些二进制模式协议绑定， + 此字段直接能映射到相应协议的内容类型的元数据属性上。 + 二进制模式和内容类型元数据映射的规范规则可以在各自的协议中找到。 + + 在某些事件格式中，可以省略 `datacontenttype` 属性。 + 例如，如果 JSON 格式的事件没有 `datacontenttype` 属性， + 则表示该`data`是符合“application/json”媒体类型的 JSON 值。 + 换句话说：一个没有 `datacontenttype` 的 JSON 格式的事件完全等同于 + 一个带有 `datacontenttype="application/json"`的事件。 + + 当将没有 `datacontenttype` 属性的事件消息转换为不同的格式或协议绑定时， + 目标 `datacontenttype` 应该显式设置为事件源的隐含或默认的 `datacontenttype`。 + +- 约束条件: + - 可选的 + - 若有则必须遵守 + [RFC 2046](https://tools.ietf.org/html/rfc2046) 制定的格式 +- 媒体类型示例 [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml) #### dataschema -- Type: `URI` -- Description: Identifies the schema that `data` adheres to. Incompatible - changes to the schema SHOULD be reflected by a different URI. See - [Versioning of Attributes in the Primer](primer.md#versioning-of-attributes) - for more information. -- Constraints: - - OPTIONAL - - If present, MUST be a non-empty URI +- 类型: `URI` +- 描述: 标识 `data` 遵守的规范。 对模式的不兼容的更改应该由不同的 URI 体现。 在 + [入门文档-属性版本控制](primer.md#属性版本控制) + 中查看更多信息。 +- 约束条件: + - 可选的 + - 若有必须是非空的 URI #### subject -- Type: `String` -- Description: This describes the subject of the event in the context of the - event producer (identified by `source`). In publish-subscribe scenarios, a - subscriber will typically subscribe to events emitted by a `source`, but the - `source` identifier alone might not be sufficient as a qualifier for any - specific event if the `source` context has internal sub-structure. - - Identifying the subject of the event in context metadata (opposed to only in - the `data` payload) is particularly helpful in generic subscription filtering - scenarios where middleware is unable to interpret the `data` content. In the - above example, the subscriber might only be interested in blobs with names - ending with '.jpg' or '.jpeg' and the `subject` attribute allows for - constructing a simple and efficient string-suffix filter for that subset of - events. - -- Constraints: - - OPTIONAL - - If present, MUST be a non-empty string -- Example: - - A subscriber might register interest for when new blobs are created inside a - blob-storage container. In this case, the event `source` identifies the - subscription scope (storage container), the `type` identifies the "blob - created" event, and the `id` uniquely identifies the event instance to - distinguish separate occurrences of a same-named blob having been created; - the name of the newly created blob is carried in `subject`: +- 类型: `String` +- 描述: 这个属性描述了事件生产者 (由`source`标识) 上下文环境中的主题信息。 + 在发布-订阅场景中，订阅者通常会订阅`source`发出的事件， + 但如果`source` 的上下文环境具有内部子结构， + 则单独的`source`标识符可能不足以作为任何指定事件的限定符。 + + 在上下文元数据中识别事件的主题（与仅在数据负载中相反） + 对于中间件无法解释`data` 内容的通用订阅过滤场景特别有用。 + 在上面的示例中，订阅者可能只对名称以“.jpg”或“.jpeg”结尾的blob感兴趣， + 此时`subject` 属性允许为该事件子集构建简单有效的字符串后缀过滤器。 + +- 约束条件: + - 可选的 + - 若有必须是非空字符串 +- 示例: + - 订阅者可能对在blob在blob存储容器中创建的时候感兴趣并订阅。 + 在这个场景下，事件`source`标示出订阅的范围（存储容器），`type` 标识出 + blob 创建" 这个事件，`id` 唯一标识出事件示例，以区分已创建同名blob的事件， + 而新创建的blob的名字可以放在`subject`属性中： - `source`: https://example.com/storage/tenant/container - `subject`: mynewfile.jpg #### time -- Type: `Timestamp` -- Description: Timestamp of when the occurrence happened. If the time of the - occurrence cannot be determined then this attribute MAY be set to some other - time (such as the current time) by the CloudEvents producer, however all - producers for the same `source` MUST be consistent in this respect. In other - words, either they all use the actual time of the occurrence or they all use - the same algorithm to determine the value used. -- Constraints: - - OPTIONAL - - If present, MUST adhere to the format specified in +- 类型: `Timestamp` +- 描述: 事件发生的时间戳。 + 如果无法确定发生的时间，则 CloudEvents 生产者可以将此属性设置为其他时间（例如当前时间）。 + 但是在这方面，同一`source`的所有生产者必须保持一致。 + 换句话说，要么它们都使用发生的实际时间，要么它们都使用相同的算法来确定所使用的值。 + +- 约束条件: + - 可选的 + - 若有则必须遵守 [RFC 3339](https://tools.ietf.org/html/rfc3339) -### Extension Context Attributes - -A CloudEvent MAY include any number of additional context attributes with -distinct names, known as "extension attributes". Extension attributes MUST -follow the same [naming convention](#attribute-naming-convention) and use the -same [type system](#type-system) as standard attributes. Extension attributes -have no defined meaning in this specification, they allow external systems to -attach metadata to an event, much like HTTP custom headers. - -Extension attributes are always serialized according to binding rules like -standard attributes. However this specification does not prevent an extension -from copying event attribute values to other parts of a message, in order to -interact with non-CloudEvents systems that also process the message. Extension -specifications that do this SHOULD specify how receivers are to interpret -messages if the copied values differ from the cloud-event serialized values. - -#### Defining Extensions - -See -[CloudEvent Attributes Extensions](primer.md#cloudevent-attribute-extensions) -for additional information concerning the use and definition of extensions. - -The definition of an extension SHOULD fully define all aspects of the -attribute - e.g. its name, type, semantic meaning and possible values. New -extension definitions SHOULD use a name that is descriptive enough to reduce the -chances of name collisions with other extensions. In particular, extension -authors SHOULD check the [documented extensions](documented-extensions.md) -document for the set of known extensions - not just for possible name conflicts -but for extensions that might be of interest. - -Many protocols support the ability for senders to include additional metadata, -for example as HTTP headers. While a CloudEvents receiver is not mandated to -process and pass them along, it is RECOMMENDED that they do so via some -mechanism that makes it clear they are non-CloudEvents metadata. - -Here is an example that illustrates the need for additional attributes. In many -IoT and enterprise use cases, an event could be used in a serverless application -that performs actions across multiple types of events. To support such use -cases, the event producer will need to add additional identity attributes to the -"context attributes" which the event consumers can use to correlate this event -with the other events. If such identity attributes happen to be part of the -event "data", the event producer would also add the identity attributes to the -"context attributes" so that event consumers can easily access this information -without needing to decode and examine the event data. Such identity attributes -can also be used to help intermediate gateways determine how to route the -events. - -## Event Data - -As defined by the term [Data](#data), CloudEvents MAY include domain-specific -information about the occurrence. When present, this information will be -encapsulated within `data`. - -- Description: The event payload. This specification does not place any - restriction on the type of this information. It is encoded into a media format - which is specified by the `datacontenttype` attribute (e.g. application/json), - and adheres to the `dataschema` format when those respective attributes are - present. - -- Constraints: - - OPTIONAL - -# Size Limits - -In many scenarios, CloudEvents will be forwarded through one or more generic -intermediaries, each of which might impose limits on the size of forwarded -events. CloudEvents might also be routed to consumers, like embedded devices, -that are storage or memory-constrained and therefore would struggle with large -singular events. - -The "size" of an event is its wire-size and includes every bit that is -transmitted on the wire for the event: protocol frame-metadata, event metadata, -and event data, based on the chosen event format and the chosen protocol -binding. - -If an application configuration requires for events to be routed across -different protocols or for events to be re-encoded, the least efficient -protocol and encoding used by the application SHOULD be considered for -compliance with these size constraints: - -- Intermediaries MUST forward events of a size of 64 KByte or less. -- Consumers SHOULD accept events of a size of at least 64 KByte. - -In effect, these rules will allow producers to publish events up to 64KB in size -safely. Safely here means that it is generally reasonable to expect the event to -be accepted and retransmitted by all intermediaries. It is in any particular -consumer's control, whether it wants to accept or reject events of that size due -to local considerations. - -Generally, CloudEvents publishers SHOULD keep events compact by avoiding -embedding large data items into event payloads and rather use the event payload -to link to such data items. From an access control perspective, this approach -also allows for a broader distribution of events, because accessing -event-related details through resolving links allows for differentiated access -control and selective disclosure, rather than having sensitive details embedded -in the event directly. - -# Privacy and Security - -Interoperability is the primary driver behind this specification, enabling such -behavior requires some information to be made available _in the clear_ resulting -in the potential for information leakage. - -Consider the following to prevent inadvertent leakage especially when leveraging -3rd party platforms and communication networks: - -- Context Attributes - - Sensitive information SHOULD NOT be carried or represented in context - attributes. - - CloudEvent producers, consumers, and intermediaries MAY introspect and log - context attributes. - -- Data +### 扩展上下文属性 + +CloudEvent 可以包含任意数量的具有不同名称的附加上下文属性，被称为"扩展属性"。 +扩展属性必须遵循相同的[命名约定](#属性命名约定)并使用与标准属性相同的 +[类型系统](#类型系统)。 +扩展属性在本规范中没有定义好的含义， +它们允许外部系统将元数据附加到事件，就像 HTTP 自定义头部一样。 + +扩展属性总是如标准属性一样，根据绑定规则进行序列化。 +然而，该规范不阻止扩展将事件属性值复制到消息的其他部分， +以便与也其它处理消息的非 CloudEvents 系统进行交互。 +如果复制的值与云事件序列化值不同，执行此操作的扩展规范应该指定接收者如何解释消息。 + +#### 定义扩展 + +在 +[CloudEvent-属性扩展](primer.md#CloudEvent-属性扩展) +查阅有关扩展使用和定义等相关信息。 + +扩展的定义应该完全定义属性的方方面面——例如 它的名称、类型、语义含义和可能的值。 +新的扩展定义应该使用一个足够描述性的名称来减少与其他扩展的名称冲突的机会。 +特别是，扩展作者应该检查[扩展文件](documented-extensions.md)中 +已知的扩展集——不仅是可能的名称冲突，还有相同目的冲突的扩展。 + +许多协议为发送者提供了包含额外元数据的能力，例如作为 HTTP 头部。 +虽然没有强制要求 CloudEvents 接受者处理和传递它们， +但建议接受者通过某种机制进行处理，以明确它们是非 CloudEvents 的元数据。 + +下面是一个示例，说明了 CloudEvents 对附加属性的需求。 +在许多物联网和企业用例中，事件可用于跨多种类型事件执行操作的serverless应用程序中。 +为了支持这样的用例，事件生产者需要向“上下文属性”添加额外的身份属性， +事件消费者可以使用这些属性将这个事件与其他事件相关联。 +如果此类身份属性恰好是事件“数据”的一部分， +则事件生产者还会将身份属性添加到“上下文属性”中， +以便事件消费者可以轻松访问此信息，而无需解码和检查事件数据。 +此类身份属性还可用于帮助中间网关确定如何路由事件。 + +## 事件数据 + +正如[数据](#数据)所定义的那样，CloudEvents 可以包括有关事件的特定域的信息。 +这些信息将被封装在`data`中。 + +- 描述: 事件负载。 本规范对该信息的类型不作任何限制。 + 它被编码为一种媒体格式，这种格式由`datacontenttype` 属性(如 application/json)指定， + 并在存在这些相应属性时遵循`dataschema`格式。 + It is encoded into a media format + +- 约束条件: + - 可选的 + +# 大小限制 + +在很多情况下，CloudEvents 将通过一个或多个通用中间人进行转发， +每个中间人都可能对转发事件的大小施加限制。 +CloudEvents 也可能直接被路由到消费者，如嵌入式设备， +这些设备是受存储或内存限制的，对单个大型事件表现不佳。 + +事件的“大小”是它的线路大小，包括在线路上为事件传输的每一位： +协议帧元数据、事件元数据和事件数据，基于所选的事件格式和所选的协议绑定。 + +如果应用程序配置需要跨不同协议路由事件或重新编码事件， +应用程序能使用的效率最低的协议和编码，都修腰符合这些大小限制： + +- 中间人转发的事件大小必须为 64 KB 或更小。 +- 消费者应该能接受大小至少为 64 KB 的事件。 + +为了方便，上述规则将允许生产者安全地发布最大 64KB 的事件。 +这里的安全意味着生产者期望事件被所有中间人接受并合理地转发。 +它是在任何特定消费者的控制之下，无论消费者是否由于本地考虑而选择接受或拒绝该大小的事件。 + +通常，CloudEvents 发布者应该通过避免将大型数据项嵌入到事件而使用事件有效链接到此类数据项， +来保持事件紧凑。 +从访问控制的角度来看，这种方法对更广泛的事件分布式化有帮助， +因为通过解析链接访问与事件相关的细节能实现差异化访问控制和选择性披露， +而不是将敏感详细数据直接嵌入到事件中。 + +# 隐私与安全 + +互操作性是本规范背后的主要驱动力， +实现此目标需要一些信息明确可用，这可能导致信息的泄漏。 + +考虑以下事项以防止信息意外泄漏，尤其是在利用第三方平台和通信网络时： + +- 上下文属性 + + 敏感信息不应在上下文属性中携带。 + + CloudEvent 生产者、消费者和中间人可以自查并记录下上下文属性。 + +- 数据 + + 特定的[事件数据](#事件数据) 应该被加密以限制对受信任方的可见性。 + 用于这种加密的机制是生产者和消费者之间的协议，不在本规范的讨论范围内。 + +- 协议绑定 + 应该采用协议级别的安全性机制来确保 CloudEvents 完成可信和安全的交换。 - Domain specific [event data](#event-data) SHOULD be encrypted to restrict - visibility to trusted parties. The mechanism employed for such encryption is - an agreement between producers and consumers and thus outside the scope of - this specification. - -- Protocol Bindings - - Protocol level security SHOULD be employed to ensure the trusted and secure - exchange of CloudEvents. - -# Example +# 示例 -The following example shows a CloudEvent serialized as JSON: +以下示例展示了一个序列化为 JSON 的 CloudEvent： ```JSON { From 8fa3995969f3c25cf902fb2dddccfd3d9a890606 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 14:34:22 +0800 Subject: [PATCH 39/60] Update primer.md Signed-off-by: JieDing --- primer.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/primer.md b/primer.md index 08a69951f..e0d42efef 100644 --- a/primer.md +++ b/primer.md @@ -1,5 +1,10 @@ # CloudEvents 入门文档 - 1.0 版本 +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. + ## 摘要 这份非技术规范文档用来为你提供关于CloudEvents规范的总体概览。它补充了CloudEvents规范的相关背景以及在制定 From f47f3edf9ee24d4f71e15099e5f928e744089b6d Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 14:34:25 +0800 Subject: [PATCH 40/60] Update README.md Signed-off-by: JieDing --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 035a7b928..34db8c3c0 100644 --- a/README.md +++ b/README.md @@ -45,8 +45,9 @@ CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvent | Primer | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/primer.md) | [master](https://github.com/cloudevents/spec/blob/master/primer.md) | | Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | -对于初次接触CloudEvents的同学，建议通过阅读[入门文档](primer.md)增加对CloudEvents规范的目标和设计理念 -的总体理解，然后再继续阅读[核心规范](spec.md)。 +对于初次接触CloudEvents的同学，可以通过阅读[入门文档](primer.md)增加对CloudEvents规范的目标和设计理念 +的总体理解， +希望在最短时间内使用CloudEvents 规范的同学，可以直接阅读[核心规范](spec.md)。 由于并非所有事件生产者都默认生产符合CloudEvents规范的事件，因此可以用[CloudEvents适配器](https://github.com/cloudevents/spec/blob/master/adapters.md) 来将现有的事件与CloudEvents做适配。 From 4ce4d10c0df3e8ab41be66b7ec28fad7c34cfd8d Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 14:36:12 +0800 Subject: [PATCH 41/60] Update README.md Signed-off-by: JieDing --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 34db8c3c0..57e49fc9e 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvent ## 步骤 -CloudEvents项目 [旨在](primer.md#design-goals)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 +CloudEvents项目 [旨在](primer.md#设计目标)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 的[标准](spec.md)。 为了完成这个目标，这个项目必须描述： @@ -95,7 +95,7 @@ CloudEvents项目 [旨在](primer.md#design-goals)制定一个能够提升不同 会议日期请查看 [CNCF 公开活动日历](https://www.cncf.io/community/calendar/). CloudEvents规范由 -[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless)开发完成。 +[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 开发完成。 这个工作组每周四的上午9点(美国-太平洋时间)通过Zoom开展视频会议。 通过 PC, Mac, Linux, iOS or Android来参加活动: https://zoom.us/my/cncfserverlesswg From 18900be8922573de3bc04462eb1e3bf5cb2f6885 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 15:32:15 +0800 Subject: [PATCH 42/60] Update primer.md Signed-off-by: JieDing --- primer.md | 113 +++++++++++++++++++++++++++--------------------------- 1 file changed, 56 insertions(+), 57 deletions(-) diff --git a/primer.md b/primer.md index e0d42efef..a5382f71f 100644 --- a/primer.md +++ b/primer.md @@ -7,9 +7,9 @@ It is strongly recommended to read the English version if you find anything lost ## 摘要 -这份非技术规范文档用来为你提供关于CloudEvents规范的总体概览。它补充了CloudEvents规范的相关背景以及在制定 -本规范时的历史和设计理念。这样，CloudEvents规范就只需要关注Events规范的技术细节，而不用过多地关心 -背景相关内容。 +这份非技术规范文档用来为你提供关于CloudEvents规范的总体概览。它补充了CloudEvents规范的相关背景 +以及在制定 本规范时的历史和设计理念。这样，CloudEvents的核心规范就只需要关注Events规范的技术细节， +而不用过多地关心背景相关内容。 ## 目录 @@ -30,17 +30,17 @@ It is strongly recommended to read the English version if you find anything lost ## 历史 -[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless)是由 CNCF的 +[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 是由 CNCF的 [技术监管委员会](https://github.com/cncf/toc) 成立，用于研究 -Serverless相关技术并为CNCF推荐相关领域的未来发展计划。其中一项建议就是研究创建一种通用事件格式， +Serverless相关技术并为CNCF推荐相关领域的未来发展计划的。工作组其中一项建议就是研究创建一种通用事件格式， 用于提升不同云厂商间函数的可移植性和事件流处理的互操作性。就此，CloudEvents应运而生。 尽管CloudEvents起初是作为Serverless工作组的项目进行的，但随着CloudEvents规范完成它v0.1版本的里程碑， -技术监管委员会批准了CloudEvents工作作为一个新的独立的CNCF沙箱级项目。 +技术监管委员会批准了CloudEvents作为一个新的独立的CNCF沙箱级项目。 ## CloudEvents-概念 -一个[事件](spec.md#event)包含了[事件发生](spec.md#occurrence)的上下文和相关数据。 +一个[事件](spec.md#事件)包含了[事件发生](spec.md#发生)的上下文和相关数据。 事件的相关数据可以用来唯一标识一件事件的发生。 事件代表了已发生的事实，因此它并不包含任何目的地相关信息，但消息能够传达事件内容，从而将事件数据 @@ -67,7 +67,7 @@ arrow pointing to a box representing the action. The arrow is annotated with 事件可以通过各种行业标准协议（如HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或 平台/供应商专有协议（AWS Kinesis、Azure Event Grid）传输。 -一个操作函数能够处理那些定义了行为或影响的事件，这些行为和效果由来自特定来源的特定事件触发而来。 +一个操作函数能够处理那些定义了行为或影响的事件，这些行为和效果由来自特定源的特定事件触发而来。 虽然超出了规范的范围，但生成事件的目的通常是让其他系统能够轻松地对它们无法控制的源中的更改做出反应。 源和操作通常由不同的开发人员构建。 通常，源是托管服务，而操作是serverless函数（如 AWS Lambda 或 Google Cloud Functions）中 @@ -75,7 +75,7 @@ arrow pointing to a box representing the action. The arrow is annotated with ## 设计目标 -CloudEvents 通常用于分布式系统，以允许服务在开发过程中松耦合，独立部署，之后可以连接以创建新的应用程序。 +CloudEvents 通常用于分布式系统，以允许服务在开发过程中松耦合，独立部署，方便之后连接以创建新的应用程序。 CloudEvents 规范的目标是定义允许服务生产或消费事件的事件系统的互操作性， 其中生产者和消费者可以独立开发和部署。 生产者可以在没有消费者监听时就生成事件， @@ -84,21 +84,21 @@ CloudEvents 规范的目标是定义允许服务生产或消费事件的事件 CloudEvents的核心规范中定义了一组称之为属性的元数据， 它们描述了在系统之间传输的事件以及这些元数据片段应如何显示在该消息中。 -这些元数据是，将请求路由到适当组件并帮助该组件正确处理事件，所需的最小信息集。 +这些元数据是，将请求路由到适当组件并帮助该组件正确处理事件所需的最小信息集。 因此，某些事件本身的数据可能会作为 CloudEvent 属性集的一部分而被复制， 但这样做仅是为了能够正确传递和处理消息。那些不用于该目的的数据应放置在事件（数据）本身中。 -此外，本规范中假设协议层所需，用来将消息传递到目标系统的元数据应完全由协议处理， -因此不包含在 CloudEvents 属性中。 有关更多详细信息，请参阅非目标部分。 +此外，本规范中假设协议层所需的用来将消息传递到目标系统的元数据应完全由协议处理， +因此不包含在 CloudEvents 属性中。 有关更多详细信息，请参阅[非目标](#非目标)部分。 除了这些属性的定义之外，规范还描述了关于如何序列化 -不同格式（例如 JSON）和协议（例如 HTTP、AMQP、Kafka）事件。 +不同格式（例如 JSON）和协议（例如 HTTP、AMQP、Kafka）的事件。 -一些协议本身支持将多个事件批处理到单个 API 调用中。 +一些协议本身支持将多个事件批处理到单个 API 的调用中。 为了提升系统间的互操作性，是否以及如何实现批处理将由协议自己决定。 相关详细信息可以在协议绑定或协议规范中找到。 成批的CloudEvents并没有语义，也没有排序。 -[中间人](spec.md#intermediary)可以添加或删除批处理以及将事件分配给不同的批处理。 +[中间人](spec.md#中间人)可以添加或删除批处理以及将事件分配给不同的批处理。 ### 非目标 @@ -110,7 +110,7 @@ CloudEvents的核心规范中定义了一组称之为属性的元数据， - 包含协议级路由信息 - 事件持久化过程 -就连那些刚接触 CloudEvents 概念的人都普遍建议 +就连那些刚接触 CloudEvents 概念的人都会建议 CloudEvents 规范不应包括协议级路由信息（例如，将事件发送到的目标的URL）。 经过深思熟虑，工作组得出的结论是，CloudEvents规范中不需要路由信息： 因为任何现有的协议（例如 HTTP、MQTT、XMPP 或 Pub/Sub 总线）都已经定义了路由语义。 @@ -120,9 +120,9 @@ CloudEvents 不需要在规范中包含目标 URL 即可与 HTTP 兼容；HTTP 路由信息不仅是多余的，而且是有害的。 CloudEvents 应该增加互操作性并解耦事件的生产者和消费者。 -禁止来自事件格式的路由信息允许将 CloudEvents 重新传送到新操作，或通过包含多个通道的复杂中继传送。 +禁止来自事件格式的路由信息允许将 CloudEvents 重新传送到新的行为，或通过包含多个通道的复杂中继传送。 例如，如果 Webhook 地址不可用，则用于 Webhook 的 CloudEvent 应可传送到死信队列。 -死信队列应该能够将事件提供给原始事件发射器从未想象过的新操作。 +死信队列应该能够将事件传送给原始事件发射者从未想象过的新的行为上。 在系统内和跨系统生产和消费的 CloudEvent能够触发产生价值的行为。 因此，对于调试或复制的目的而言，存档和或重放事件可能很有价值。 @@ -137,7 +137,7 @@ CloudEvents 规范集定义了四种有助于形成分层架构模型的不同 1. [基本规范](spec.md) 定义了一个抽象信息模型， 该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 -2. [扩展](./spec.md#extension-context-attributes) +2. [扩展属性](./spec.md#扩展上下文属性) 添加了特定于用例且可能重叠的扩展属性集和相关规则，如支持不同的追踪标准的规则。 3. 事件格式编码,如 [JSON](json-format.md), 定义了基本规范的信息模型与所选扩展的编码方式， 以将其映射到应用程序协议的头部和负载元素。 @@ -180,7 +180,7 @@ CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强 `id` 属性是一个在同一事件源下所有事件中用来标识事件唯一的值 （其中每个事件源由其 CloudEvents `source`属性唯一标识）。 虽然`id`使用的确切值是生产者定义的， -但可以确保来自单个事件源的 CloudEvents 消费者不会有两个事件共享相同的 id 值。 +但必须要确保来自单个事件源的 CloudEvents 消费者不会有两个事件共享相同的 id 值。 唯一的例外是如果支持事件的重播，在这些情况下，可以使用 id 来检测这一点。 由于一次事件的发生可能导致生成多个cloud event， @@ -211,16 +211,16 @@ CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强 “必要”属性是工作组认为在任何情况下，对所有事件都至关重要的属性， 而“可选”属性将在大多数情况下使用。 这些情况下的两个属性都在本规范中定义了出来。 -当工作组考虑到某些属性不够常见而不能归入上述两个类别， +工作组考虑到某些属性不够常见而不能归入上述两个类别， 但此类属性的良好定义仍会使系统间的互操作性级别受益， -则将这些属性放入了“扩展”类别并记录在[扩展文档](documented-extensions.md)中， +因此将这些属性放入了“扩展”类别并记录在[扩展文档](documented-extensions.md)中， 本规范定义了这些扩展属性在 CloudEvent 中的显示方式。 在确定提议的属性属于哪个类别时， 工作组使用现有的用例和用户故事来解释它们的基本原理和需求。 -相关信息将添加到本文档的[现有技术](#prior-art)部分。 +相关信息将添加到本文档的[现有技术](#现有技术)部分。 -CloudEvent 规范的扩展属性是需要包含的附加元数据，它们能确保合适的路由和正确处理CloudEvent。 +CloudEvent 规范的扩展属性是需要包含的附加元数据，它们能确保正确的路由和正确处理CloudEvent。 用于其它目的的附加元数据， 即那些与事件本身相但在 CloudEvent 的传输或处理中不需要的元数据， 应改为放置在事件 (`data`)的扩展点内。 @@ -244,12 +244,12 @@ CloudEvent 扩展属性与已定义属性(必要属性、可选属性)在序列 CloudEvent的作者花了很长时间考虑所有选项，并认为这是最好的选择。 理由如下： -由于CloudEvents规范遵循 [semver](https://semver.org/)， -这意味着只要新属性是可选属性，它们可以由核心规范的未来版本定义，而无需更改主要版本。 -在这些情况下，请考虑现有消费者将如何使用新的（未知）顶级属性。 +由于CloudEvents规范遵循 [semver](https://semver.org/) ， +这意味着只要新属性是可选属性，它们可以在核心规范的未来版本定义，而无需更改当前主要版本。 +在这样的情况下，请考虑现有消费者将如何使用新的（未知的）顶级属性。 虽然消费者可以随意忽略它，因为它是可选的， -但在大多数情况下，这些属性仍然希望向接收这些事件的应用公开。 -这将允许这些应用程序支持这些属性，即使基础设施不支持。 +但在大多数情况下，这些属性仍然希望向接收这些事件的应用程序公开。 +这可能导致这些应用程序在基础设施不支持的情况下，支持这些属性。 这意味着未知的顶级属性（无论是谁定义的——规范的未来版本或事件生产者）可能不会被忽略。 因此，虽然其它一些规范定义了放置扩展的特定属性（例如顶级`extensions`属性）， 但作者认为在传入事件中具有两个不同位置的未知属性可能会导致互操作性问题和开发人员的混淆。 @@ -259,20 +259,20 @@ CloudEvent的作者花了很长时间考虑所有选项，并认为这是最好 那么如果该属性被核心规范采用，它将从`extensions`属性提升（从序列化的角度）为顶级属性。 如果我们假设这个新属性是可选的，那么当它被核心规范采用时， 它只是一个小版本增量，所有现有的消费者仍然会继续工作。 -但是，消费者将不知道此属性将出现在何处 - 在扩展属性中或是作为顶级属性。 +但是，消费者将不知道此属性将出现在何处 - 在扩展属性中还是作为顶级属性。 这意味着他们可能需要同时查看两个地方。 如果属性出现在两个地方但具有不同的值怎么办？ -生产者是否需要将它放在两个地方，因为他们可能有新老消费者？ -虽然有可能为如何解决出现的每个潜在问题定义明确的规则， +生产者是否需要将它放在两个地方，因为他们可能同时有新、老消费者？ +虽然可以为如何解决出现的每个潜在问题而制定明确的规则， 但作者认为一个避免这些问题的更好的办法是在序列化中只有一个位置来放置未知的甚至是新的属性。 作者还注意到 HTTP 规范现在遵循类似的模式，不再建议扩展 HTTP 头部以 X- 为前缀。 ## 生产CloudEvents CloudEvents 规范有意避免将CloudEvents 的创建方式设计的过于死板。 -例如，它不假定原始事件源必须是该事件构造关联 CloudEvent 的同一实体。 +例如，它不假定原始事件源必须是该事件生产对应 CloudEvent 的同一实体。 这允许多种实现方式。 -但是，对于规范的实现者来说，理解规范作者心中的期望是很有用的，因为这将有助于确保互操作性和一致性。 +但是，对于规范的实现者来说，理解规范作者心中的期望还是有帮助的，因为这将有助于确保互操作性和一致性。 如上所述，生成初始事件的实体是否与创建相应 CloudEvent 的实体相同是由实现决定的。 但是，当构建/填充 CloudEvents 属性的实体代表事件源进行操作时，这些属性的值是用来描述事件或事件源， @@ -298,7 +298,7 @@ CloudEvents 规范有意避免将CloudEvents 的创建方式设计的过于死 但是，如果此实体正在执行 CloudEvent 的某种类型的语义处理， 通常会导致`data`属性值发生更改， 则可能需要将其视为与原始事件源不同的“事件源”。 -因此，预计与事件生产者相关的 CloudEvents 属性（例如`source` and `id`） +因此，与事件生产者相关的 CloudEvents 属性（例如`source` and `id`） 将从传入的 CloudEvent 中更改。 ## 合格的协议与编码 @@ -317,7 +317,7 @@ CloudEvents 旨在提供这种开放的数据格式，并将其数据格式映 例如 HTTP 1.1 和 HTTP/2 以及 WebSockets 或 Web 上的事件，或者 MQTT 和 AMQP 用于面向连接的消息传递和遥测传输的协议。 -一些广泛使用的协议已经成为事实上的标准，这些协议来自三个或更多公司的顶级财团的强大生态系统， +一些广泛使用的协议已经成为事实上的标准，这些协议来自三个或更多公司的顶级财团打造的强大生态系统， 还有一些来自单个公司发布的强大项目生态系统，在任何一种情况下都与前面提到的标准栈的演变相一致。 CloudEvents的努力不应成为认可或推广项目或产品专有协议的工具， @@ -337,14 +337,14 @@ CloudEvents的努力不应成为认可或推广项目或产品专有协议的工 对此的基本要求是协议或编码的定义方式允许独立于产品或项目代码的替代实现。 欢迎将 CloudEvents 的所有其他协议和编码格式 -包含在指向相应项目自己的公共存储库或站点中的 CloudEvents binding信息的列表中。 +包含在指向相应项目自己的公共仓库，或站点中的 CloudEvents binding信息的列表中。 ## 专有的协议与编码 为了鼓励更多人采用 CloudEvents，本仓库将自动收集专有协议和编码。 本仓库的维护人员不负责创建、维护或通知专有规范的维护人员有关专有规范和CloudEvents规范间的偏差。 -专有规范将托管在他们自己的仓库或文档站点中，并收集在[专有规范](proprietary-specs.md) +专有规范将托管在他们自己的仓库或文档站点中，并记录在[专有规范](proprietary-specs.md) 文件中。 专有规范应遵循与核心协议和编码相关的其他规范相同的格式。 专有规范将比核心规范受到更少的审查，并且随着 CloudEvents 规范的发展， @@ -362,7 +362,7 @@ CloudEvents的努力不应成为认可或推广项目或产品专有协议的工 下面列举了可能涉及事件的产生、管理或消费的各种参与者和场景。 在这些中，事件生产者和事件消费者的角色是不同的。 -单个应用程序上下文始终可以同时承担多个角色，包括既是事件的生产者又是事件的消费者。 +单个应用程序上下文背景始终可以同时承担多个角色，包括既是事件的生产者又是事件的消费者。 1. 应用程序生成供他人使用的事件， 如为消费者提供有关终端用户活动、状态变化或环境观察的见解， @@ -378,7 +378,7 @@ CloudEvents的努力不应成为认可或推广项目或产品专有协议的工 作为后者的示例，请考虑设备通过负载大小受限的网络（如 LoRaWAN 或 ModBus）传输的事件数据， 并且符合此规范的事件将由网络网关代表生产者提供。 - 例如，气象站每 5 分钟通过 LoRaWAN 传输一次 12 字节的专有事件有效载荷用于指示天气状况。 + 例如，气象站每 5 分钟通过 LoRaWAN 传输一次 12 字节的专有事件payload用于指示天气状况。 然后使用 LoRaWAN 网关以 CloudEvents 格式将事件发布到 Internet 目标。 LoRaWAN 网关是事件生产者，代表气象站发布事件，并将设置一定的元数据以反映事件的来源(气象站)。 @@ -400,18 +400,17 @@ CloudEvents的努力不应成为认可或推广项目或产品专有协议的工 - 从原始上下文中获取有关事件主题的更多详细信息，例如获取有关需要特权访问授权的已更改对象的详细信息。 例如，出于隐私原因，HR 解决方案可能仅在事件中发布非常有限的信息， - 任何需要更多数据的事件消费者都必须在其自己的授权上下文下从 HR 系统获取与事件相关的详细信息 + 任何需要更多数据的事件消费者都必须在其自己的授权上下文背景下从 HR 系统获取与事件相关的详细信息 - 在原始上下文中与事件的主题进行交互，例如在被告知该数据块刚刚创建后读取存储该数据块。 消费者的兴趣激发了信息生产者应该包括事件的需求。 3. 中间件将事件从生产者路由到消费者，或转发到其他中间件。 - 产生事件的应用程序可能会将消费者需求产生的某些任务委托给中间件： + 产生事件的应用程序可能会将根据消费者需求产生的某些任务委托给中间件： - - Management of many concurrent interested consumers for one of multiple - classes or originating contexts of events + - 管理同时对大量类别和上下文背景中的某个事件感兴趣的消费者。 - 代表消费者在类或事件的原始上下文上处理过滤条件。 - - 转码，比如从 JSON 解码后在 MsgPack 中编码 + - 转码，比如从 JSON 解码后在 MsgPack 中编码。 - 更改事件结构的转换，例如从专有格式映射到 CloudEvents，同时保留事件的身份和语义完整性。 - 即时“推送式”传输给感兴趣的消费者。 - 存储最终传输的事件，用于由消费者发起的“拉”请求，或延迟后由中间件发起“推”请求。 @@ -422,24 +421,24 @@ CloudEvents的努力不应成为认可或推广项目或产品专有协议的工 - 一种元数据鉴别器，可用于事件的分类或上下文化，以便消费者可以表达对一个或多个类或上下文的兴趣。 例如，消费者可能对文件存储帐户内的特定目录相关的所有事件感兴趣。 - 一种元数据鉴别器，允许区分该类或上下文的特定事件的主题。例如，消费者可能希望过滤掉与以“.jpg”结尾的 - 新文件相关的所有事件（文件名是“新文件”事件的主题）， - 用于描述其已注册的文件存储帐户内的特定目录的上下文兴趣。 + 新文件相关的所有事件（文件名是“新文件”事件的主题），以此表示它对感兴趣的文件存储账户下某个目录的 + 上下文环境。 - 一个事件及其数据编码的指示器。 - 一个事件及其数据的结构布局（模式）的指示器。 事件是否可通过中间件消费取决于生产者的选择。 - 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec.md#producer)的角色， - 当它根据事件采取行动时可以扮演[消费者](spec.md#consumer)的角色， - 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec.md#intermediary)的角色。 + 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec.md#生产者)的角色， + 当它根据事件采取行动时可以扮演[消费者](spec.md#消费者)的角色， + 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec.md#中间人)的角色。 -4. 框架和其他抽象使与事件平台基础设施的交互更简单， +4. 框架和其他抽象使与事件平台基础设施间的交互更简单， 并且通常为多个事件平台基础设施提供公共 API 区域。 - 框架通常用于将事件转换为对象图，并将事件分派给某些特定的处理用户代码或用户规则， - 这些用户代码或用户规则允许消费应用程序对原始上下文和特定主题中的特定类型的事件做出反应。 + 框架通常用于将事件转换为对象图，并将事件分派给某些特定的处理逻辑或用户规则， + 这些用户逻辑或用户规则允许消费应用程序对原始上下文和特定主题中的特定类型的事件做出反应。 - 框架最感兴趣的是跨它们抽象的平台的语义元数据通用性，以便可以统一处理类似的活动。 + 框架最感兴趣的是跨抽象平台的语义元数据通用性，以便可以统一处理类似的活动。 对于体育应用程序，使用该框架的开发人员可能对联盟中一支球队今天的比赛（主题） 的所有事件感兴趣，但希望以不同于“换人”事件的方式处理“得分”事件。 @@ -487,7 +486,7 @@ CloudEvents 可以提供更好的开发工具来构建、测试和处理事件 大多数平台和服务对其事件的数据模型进行不同的版本控制（如果他们这样做的话）。 随着这些数据模型的发展，这会为发布和使用事件的数据模型带来不一致的体验。 -CloudEvents 可以提供一种通用的方式来版本化和发展事件数据。 +CloudEvents 可以提供一种通用的方式来版本化和演化事件数据的发展。 这将帮助事件发布者根据最佳实践安全地对其数据模型进行版本控制， 并且这有助于事件消费者随着事件数据的发展安全地使用它。 @@ -507,8 +506,8 @@ CloudEvents 可以提供 Webhook 发布和消费事件的一致性。 #### 事件追踪 -从源发送的事件可能会出现在一系列附加事件之间， -这些附加事件从各种中间件设备（例如事件代理和网关）发出的。 +从源发送的事件可能会出现在一系列附加事件序列之中， +这些附加事件序列从各种中间件设备（例如事件代理和网关）发出。 CloudEvents 在事件中包含元数据以将这些事件关联为事件序列的一部分，以便进行事件跟踪和故障排除。 #### IoT From cfdb705f28f6e86c85a8ae9b11e68807a94cc690 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 15:40:21 +0800 Subject: [PATCH 43/60] Update spec.md Signed-off-by: JieDing --- spec.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/spec.md b/spec.md index 1f1428ec8..7c9c1a8cd 100644 --- a/spec.md +++ b/spec.md @@ -1,10 +1,13 @@ # CloudEvents 核心规范- 1.0 版本 +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. + ## 摘要 CloudEvents 是一个用于定义事件格式的供应商中立规范。 -CloudEvents is a vendor-neutral specification for defining the format of event -data. ## 目录 @@ -64,7 +67,7 @@ CloudEvents是一个以通用格式来描述事件数据的标准。它提供了 #### 事件 -“事件”是表示"发生"及其上下文的数据记录。 +“事件”是表示一条"发生"及其上下文的数据记录。 事件从事件生产者（源）路由到对它感兴趣的事件消费者。 事件中包含的信息帮助完成路由操作，但事件不会标识特定的路由目的地。 事件将包含两种类型的信息：表示"发生"的 [事件数据](#事件数据) @@ -89,7 +92,7 @@ CloudEvents是一个以通用格式来描述事件数据的标准。它提供了 一个“中间人”会接收包含事件的消息， 并将其转发给下一个接收者，但该接收者可能是另一个中间人或事件[消费者](#消费者)。 -中间人的典型任务就是根据[上下文](#context)环境中的信息将事件路由到接收者。 +中间人的典型任务就是根据[上下文](#上下文)环境中的信息将事件路由到接收者。 #### 上下文 @@ -113,7 +116,7 @@ CloudEvents是一个以通用格式来描述事件数据的标准。它提供了 “结构化模式消息”是一种使用独立事件格式对事件进行完全编码并存储在消息体中的消息。 -“二进制模式消息”是将事件数据存储在消息体中，并将事件属性作为消息元数据的一部分存储下来。 +“二进制模式消息”会将事件数据存储在消息体中，并将事件属性作为消息元数据的一部分存储下来。 #### 协议 @@ -136,7 +139,7 @@ CloudEvents是一个以通用格式来描述事件数据的标准。它提供了 ### 属性命名约定 -CloudEvents 规范定义了到各种协议和编码的映射，随附的 CloudEvents SDK 面向各种运行时和语言。 +CloudEvents 规范定义了到各种协议和编码的映射，随附的 CloudEvents SDK 面向各种运行时和编程语言。 其中一些将元数据元素区分大小写，而另一些则不区分， 并且单个 CloudEvent 可能通过涉及到协议、编码和运行时混合的多个跃点进行路由。 因此，本规范限制了所有属性的可用字符集，以防止区分大小写问题或与通用语言中标识符的合法字符集冲突问题。 From 5f392106aa6c103bd0c9abbea03da1e8e122ff11 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:23:09 +0800 Subject: [PATCH 44/60] Create README_CN.md Signed-off-by: JieDing --- README_CN.md | 132 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 README_CN.md diff --git a/README_CN.md b/README_CN.md new file mode 100644 index 000000000..57e49fc9e --- /dev/null +++ b/README_CN.md @@ -0,0 +1,132 @@ +# CloudEvents Chinese Manual + +![CloudEvents logo](https://github.com/cncf/artwork/blob/master/projects/cloudevents/horizontal/color/cloudevents-horizontal-color.png) + +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. + +事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 + +对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。它同样限制了那些用来帮助事件数据完成 +跨环境传输的库(如SDKs)，工具(如事件路由器)和基础设施(如事件追踪系统)的发展。总体来看，这种匮乏严重阻碍了事件数据的 +可移植性和生产力。 + +CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 + +CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvents被[云原生计算基金会](https://cncf.io) (CNCF)持有， +在[2018/05/15](https://docs.google.com/presentation/d/1KNSv70fyTfSqUerCnccV7eEC_ynhLsm9A_kjnlmU_t0/edit#slide=id.g37acf52904_1_41) +被选为云原生沙箱级项目。 + +## CloudEvents 文件 + +现有文件如下: + +| | 最新版本 | 工作草稿 | +| :---------------------------- | :----------------------------------------------------------------------------: | :---------------------------------------------------------------------------------: | +| **核心标准:** | +| CloudEvents | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/spec.md) | [master](https://github.com/cloudevents/spec/blob/master/spec.md) | +| | +| **可选标准:** | +| AMQP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/amqp-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-protocol-binding.md) | +| AVRO Event Format | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/avro-format.md) | [master](https://github.com/cloudevents/spec/blob/master/avro-format.md) | +| HTTP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/http-protocol-binding.md) | +| JSON Event Format | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/json-format.md) | [master](https://github.com/cloudevents/spec/blob/master/json-format.md) | +| Kafka Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/kafka-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/kafka-protocol-binding.md) | +| MQTT Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/mqtt-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/mqtt-protocol-binding.md) | +| NATS Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/nats-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/nats-protocol-binding.md) | +| Web hook | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md) | [master](https://github.com/cloudevents/spec/blob/master/http-webhook.md) | +| | +| **附加文件:** | +| CloudEvents Adapters | - | [master](https://github.com/cloudevents/spec/blob/master/adapters.md) | +| CloudEvents SDK Requirements | - | [master](https://github.com/cloudevents/spec/blob/master/SDK.md) | +| Documented Extensions | - | [master](https://github.com/cloudevents/spec/blob/master/documented-extensions.md) | +| Primer | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/primer.md) | [master](https://github.com/cloudevents/spec/blob/master/primer.md) | +| Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | + +对于初次接触CloudEvents的同学，可以通过阅读[入门文档](primer.md)增加对CloudEvents规范的目标和设计理念 +的总体理解， +希望在最短时间内使用CloudEvents 规范的同学，可以直接阅读[核心规范](spec.md)。 + +由于并非所有事件生产者都默认生产符合CloudEvents规范的事件，因此可以用[CloudEvents适配器](https://github.com/cloudevents/spec/blob/master/adapters.md) +来将现有的事件与CloudEvents做适配。 + +## SDKs + +除了上述文档，我们还提供了[SDK 提议](SDK.md)以及一些编程语言的SDK： + +- [CSharp](https://github.com/cloudevents/sdk-csharp) +- [Go](https://github.com/cloudevents/sdk-go) +- [Java](https://github.com/cloudevents/sdk-java) +- [Javascript](https://github.com/cloudevents/sdk-javascript) +- [Python](https://github.com/cloudevents/sdk-python) + +## 社区 + +在社区里，你可以了解到更多致力于搭建一个动态、云原生的生态系统的成员和组织。 +他们不断尝试提升现有系统和CloudEvents间的互操作性和兼容性。 + +- [贡献者](community/contributors.md): + 是指那些帮助我们制定规范或是积极活跃在CloudEvents规范相关工作的成员和组织。 +- 即将推出: [demos & open source](community/README.md) -- + 如果你希望向我们分享关于你对CloudEvents的使用，请通过提交PR让我们看到。 + +## 步骤 + +CloudEvents项目 [旨在](primer.md#设计目标)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 +的[标准](spec.md)。 + +为了完成这个目标，这个项目必须描述： + +- 一系列能够提升互操作性的用来描述事件的属性 +- 一个或多个通用架构，这些架构必须是当下活跃的或是正在计划被完成的 +- 事件是如何在一种或多种协议下从生产者传输到消费者的 +- 识别并解决任何能提升互操作性的问题 +## 联系方式 + +邮件联系方式如下: + +- 发送EMail至: [cncf-cloudevents](mailto:cncf-cloudevents@lists.cncf.io) +- 订阅地址: https://lists.cncf.io/g/cncf-cloudevents +- 存档地址: https://lists.cncf.io/g/cncf-cloudevents/topics + +## 会议时间 + +会议日期请查看 [CNCF 公开活动日历](https://www.cncf.io/community/calendar/). +CloudEvents规范由 +[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 开发完成。 +这个工作组每周四的上午9点(美国-太平洋时间)通过Zoom开展视频会议。 +通过 PC, Mac, Linux, iOS or Android来参加活动: https://zoom.us/my/cncfserverlesswg + +或者通过 iPhone one-tap : + + US: +16465588656,,3361029682# or +16699006833,,3361029682# + +或者电话接入: + + Dial: + US: +1 646 558 8656 (US Toll) or +1 669 900 6833 (US Toll) + or +1 855 880 1246 (Toll Free) or +1 877 369 0926 (Toll Free) + +会议 ID: 336 102 9682 + +国际号码接入: +https://zoom.us/zoomconference?m=QpOqQYfTzY_Gbj9_8jPtsplp1pnVUKDr + +世界时区转化器: +http://www.thetimezoneconverter.com/?t=9:00%20am&tz=San%20Francisco& + +## 会议记录 + +历史会议记录在 +[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) +查看。 + +历史会议录像在 +[这里](https://www.youtube.com/playlist?list=PLj6h78yzYM2Ph7YoBIgsZNW_RGJvNlFOt) +查看。 + +工作组会定期举办与主流会议一致的线下会议。查看[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) +了解更多未来计划。 + From 0e11f123f7f85f3fbde0ec38d759302a21c21235 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:23:42 +0800 Subject: [PATCH 45/60] Update README_CN.md Signed-off-by: JieDing --- README_CN.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README_CN.md b/README_CN.md index 57e49fc9e..d918be3d4 100644 --- a/README_CN.md +++ b/README_CN.md @@ -1,4 +1,4 @@ -# CloudEvents Chinese Manual +# CloudEvents 中文首层 ![CloudEvents logo](https://github.com/cncf/artwork/blob/master/projects/cloudevents/horizontal/color/cloudevents-horizontal-color.png) From 09b87d1c0e87ef5dfe9a8af95c03f42e24e9f0f8 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:23:55 +0800 Subject: [PATCH 46/60] Update README_CN.md Signed-off-by: JieDing --- README_CN.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README_CN.md b/README_CN.md index d918be3d4..64a4ee4f7 100644 --- a/README_CN.md +++ b/README_CN.md @@ -1,4 +1,4 @@ -# CloudEvents 中文首层 +# CloudEvents 中文手册 ![CloudEvents logo](https://github.com/cncf/artwork/blob/master/projects/cloudevents/horizontal/color/cloudevents-horizontal-color.png) From affe7df937780f57de4a78c9bbf41ad3156de8f8 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:25:50 +0800 Subject: [PATCH 47/60] Update README.md Signed-off-by: JieDing --- README.md | 146 +++++++++++++++++++++++++++++------------------------- 1 file changed, 79 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 57e49fc9e..c26f0b7df 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,35 @@ -# CloudEvents Chinese Manual +# CloudEvents ![CloudEvents logo](https://github.com/cncf/artwork/blob/master/projects/cloudevents/horizontal/color/cloudevents-horizontal-color.png) -Declaration： This manual aims to provide a fast and brief introduction of CloudEvents -in Chinese for people who are new to CloudEvents. -Most of the content is translated from the original English version. -It is strongly recommended to read the English version if you find anything lost in translation. +Events are everywhere. However, event producers tend to describe events +differently. -事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 +The lack of a common way of describing events means developers must constantly +re-learn how to consume events. This also limits the potential for libraries, +tooling and infrastructure to aide the delivery of event data across +environments, like SDKs, event routers or tracing systems. The portability and +productivity we can achieve from event data is hindered overall. -对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。它同样限制了那些用来帮助事件数据完成 -跨环境传输的库(如SDKs)，工具(如事件路由器)和基础设施(如事件追踪系统)的发展。总体来看，这种匮乏严重阻碍了事件数据的 -可移植性和生产力。 +CloudEvents is a specification for describing event data in common formats to +provide interoperability across services, platforms and systems. -CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 +CloudEvents has received a large amount of industry interest, ranging from major +cloud providers to popular SaaS companies. CloudEvents is hosted by the +[Cloud Native Computing Foundation](https://cncf.io) (CNCF) and was approved as +a Cloud Native sandbox level project on +[May 15, 2018](https://docs.google.com/presentation/d/1KNSv70fyTfSqUerCnccV7eEC_ynhLsm9A_kjnlmU_t0/edit#slide=id.g37acf52904_1_41). -CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvents被[云原生计算基金会](https://cncf.io) (CNCF)持有， -在[2018/05/15](https://docs.google.com/presentation/d/1KNSv70fyTfSqUerCnccV7eEC_ynhLsm9A_kjnlmU_t0/edit#slide=id.g37acf52904_1_41) -被选为云原生沙箱级项目。 +## CloudEvents Documents -## CloudEvents 文件 +The following documents are available: -现有文件如下: - -| | 最新版本 | 工作草稿 | +| | Latest Release | Working Draft | | :---------------------------- | :----------------------------------------------------------------------------: | :---------------------------------------------------------------------------------: | -| **核心标准:** | +| **Core Specification:** | | CloudEvents | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/spec.md) | [master](https://github.com/cloudevents/spec/blob/master/spec.md) | | | -| **可选标准:** | +| **Optional Specifications:** | | AMQP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/amqp-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-protocol-binding.md) | | AVRO Event Format | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/avro-format.md) | [master](https://github.com/cloudevents/spec/blob/master/avro-format.md) | | HTTP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/http-protocol-binding.md) | @@ -38,23 +39,26 @@ CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvent | NATS Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/nats-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/nats-protocol-binding.md) | | Web hook | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md) | [master](https://github.com/cloudevents/spec/blob/master/http-webhook.md) | | | -| **附加文件:** | +| **Additional Documentation:** | | CloudEvents Adapters | - | [master](https://github.com/cloudevents/spec/blob/master/adapters.md) | | CloudEvents SDK Requirements | - | [master](https://github.com/cloudevents/spec/blob/master/SDK.md) | | Documented Extensions | - | [master](https://github.com/cloudevents/spec/blob/master/documented-extensions.md) | | Primer | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/primer.md) | [master](https://github.com/cloudevents/spec/blob/master/primer.md) | | Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | -对于初次接触CloudEvents的同学，可以通过阅读[入门文档](primer.md)增加对CloudEvents规范的目标和设计理念 -的总体理解， -希望在最短时间内使用CloudEvents 规范的同学，可以直接阅读[核心规范](spec.md)。 +If you are new to CloudEvents, it is recommended that you start by reading the +[Primer](primer.md) for an overview of the specification's goals and design +decisions, and then move on to the [core specification](spec.md). -由于并非所有事件生产者都默认生产符合CloudEvents规范的事件，因此可以用[CloudEvents适配器](https://github.com/cloudevents/spec/blob/master/adapters.md) -来将现有的事件与CloudEvents做适配。 +Since not all event producers generate CloudEvents by default, there is +documentation describing the recommended process for adapting some popular +events into CloudEvents, see +[CloudEvents Adapters](https://github.com/cloudevents/spec/blob/master/adapters.md). ## SDKs -除了上述文档，我们还提供了[SDK 提议](SDK.md)以及一些编程语言的SDK： +In addition to the documentation mentioned above, there are also an +[SDK proposal](SDK.md) and a set of SDKs being developed: - [CSharp](https://github.com/cloudevents/sdk-csharp) - [Go](https://github.com/cloudevents/sdk-go) @@ -62,71 +66,79 @@ CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvent - [Javascript](https://github.com/cloudevents/sdk-javascript) - [Python](https://github.com/cloudevents/sdk-python) -## 社区 +## Community + +Learn more about the people and organizations who are creating a dynamic cloud +native ecosystem by making our systems interoperable with CloudEvents. + +- [Contributors](community/contributors.md): people and organizations who helped + us get started or are actively working on the CloudEvents specification. +- Coming soon: [demos & open source](community/README.md) -- if you have + something to share about your use of CloudEvents, please submit a PR! -在社区里，你可以了解到更多致力于搭建一个动态、云原生的生态系统的成员和组织。 -他们不断尝试提升现有系统和CloudEvents间的互操作性和兼容性。 +## Process -- [贡献者](community/contributors.md): - 是指那些帮助我们制定规范或是积极活跃在CloudEvents规范相关工作的成员和组织。 -- 即将推出: [demos & open source](community/README.md) -- - 如果你希望向我们分享关于你对CloudEvents的使用，请通过提交PR让我们看到。 +The CloudEvents project is working to formalize the [specification](spec.md) +based on [design goals](primer.md#design-goals) which focus on interoperability +between systems which generate and respond to events. -## 步骤 +In order to achieve these goals, the project must describe: -CloudEvents项目 [旨在](primer.md#设计目标)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 -的[标准](spec.md)。 +- Common attributes of an _event_ that facilitate interoperability +- One or more common architectures that are in active use today or planned to be + built by its members +- How events are transported from producer to consumer via at least one protocol +- Identify and resolve whatever else is needed for interoperability -为了完成这个目标，这个项目必须描述： +## Communications -- 一系列能够提升互操作性的用来描述事件的属性 -- 一个或多个通用架构，这些架构必须是当下活跃的或是正在计划被完成的 -- 事件是如何在一种或多种协议下从生产者传输到消费者的 -- 识别并解决任何能提升互操作性的问题 -## 联系方式 +The mailing list for e-mail communications: -邮件联系方式如下: +- Send emails to: [cncf-cloudevents](mailto:cncf-cloudevents@lists.cncf.io) +- To subscribe see: https://lists.cncf.io/g/cncf-cloudevents +- Archives are at: https://lists.cncf.io/g/cncf-cloudevents/topics -- 发送EMail至: [cncf-cloudevents](mailto:cncf-cloudevents@lists.cncf.io) -- 订阅地址: https://lists.cncf.io/g/cncf-cloudevents -- 存档地址: https://lists.cncf.io/g/cncf-cloudevents/topics +And a #cloudevents Slack channel under +[CNCF's Slack workspace](https://slack.cncf.io/). -## 会议时间 +## Meeting Time -会议日期请查看 [CNCF 公开活动日历](https://www.cncf.io/community/calendar/). -CloudEvents规范由 -[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 开发完成。 -这个工作组每周四的上午9点(美国-太平洋时间)通过Zoom开展视频会议。 -通过 PC, Mac, Linux, iOS or Android来参加活动: https://zoom.us/my/cncfserverlesswg +See the [CNCF public events calendar](https://www.cncf.io/community/calendar/). +This specification is being developed by the +[CNCF Serverless Working Group](https://github.com/cncf/wg-serverless). This +working group meets every Thursday at 9AM PT (USA Pacific): -或者通过 iPhone one-tap : +Join from PC, Mac, Linux, iOS or Android: https://zoom.us/my/cncfserverlesswg + +Or iPhone one-tap : US: +16465588656,,3361029682# or +16699006833,,3361029682# -或者电话接入: +Or Telephone: Dial: US: +1 646 558 8656 (US Toll) or +1 669 900 6833 (US Toll) or +1 855 880 1246 (Toll Free) or +1 877 369 0926 (Toll Free) -会议 ID: 336 102 9682 +Meeting ID: 336 102 9682 -国际号码接入: +International numbers available: https://zoom.us/zoomconference?m=QpOqQYfTzY_Gbj9_8jPtsplp1pnVUKDr -世界时区转化器: -http://www.thetimezoneconverter.com/?t=9:00%20am&tz=San%20Francisco& +NOTE: Please use \*6 to mute/un-mute your phone during the call. -## 会议记录 +World Time Zone Converter: +http://www.thetimezoneconverter.com/?t=9:00%20am&tz=San%20Francisco& -历史会议记录在 -[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) -查看。 +## Meeting Minutes -历史会议录像在 -[这里](https://www.youtube.com/playlist?list=PLj6h78yzYM2Ph7YoBIgsZNW_RGJvNlFOt) -查看。 +The minutes from our calls are available +[here](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#). -工作组会定期举办与主流会议一致的线下会议。查看[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) -了解更多未来计划。 +Recording from our calls are available +[here](https://www.youtube.com/playlist?list=PLj6h78yzYM2Ph7YoBIgsZNW_RGJvNlFOt). +Periodically, the group may have in-person meetings that coincide with a major +conference. Please see the +[meeting minutes](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) +for any future plans. From 8a50729792b6f7d00addba78cc41488c8b19e5c7 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:26:48 +0800 Subject: [PATCH 48/60] Create primer_CN.md Signed-off-by: JieDing --- primer_CN.md | 704 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 704 insertions(+) create mode 100644 primer_CN.md diff --git a/primer_CN.md b/primer_CN.md new file mode 100644 index 000000000..a5382f71f --- /dev/null +++ b/primer_CN.md @@ -0,0 +1,704 @@ +# CloudEvents 入门文档 - 1.0 版本 + +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. + +## 摘要 + +这份非技术规范文档用来为你提供关于CloudEvents规范的总体概览。它补充了CloudEvents规范的相关背景 +以及在制定 本规范时的历史和设计理念。这样，CloudEvents的核心规范就只需要关注Events规范的技术细节， +而不用过多地关心背景相关内容。 + +## 目录 + +- [历史](#历史) +- [CloudEvents 概念](#CloudEvents-概念) +- [设计目标](#设计目标) +- [架构](#架构) +- [属性版本控制](#属性版本控制) +- [CloudEvent 属性](#CloudEvent-属性) +- [CloudEvent 属性扩展](#CloudEvent-属性扩展) +- [生产 CloudEvents](#生产CloudEvents) +- [合格的协议与编码](#合格的协议与编码) +- [专有的协议和编码](#专有的协议与编码) +- [现有技术](#现有技术) +- [角色](#角色) +- [价值主张](#价值主张) +- [现有的数据格式](#现有的数据格式) + +## 历史 + +[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 是由 CNCF的 +[技术监管委员会](https://github.com/cncf/toc) 成立，用于研究 +Serverless相关技术并为CNCF推荐相关领域的未来发展计划的。工作组其中一项建议就是研究创建一种通用事件格式， +用于提升不同云厂商间函数的可移植性和事件流处理的互操作性。就此，CloudEvents应运而生。 + +尽管CloudEvents起初是作为Serverless工作组的项目进行的，但随着CloudEvents规范完成它v0.1版本的里程碑， +技术监管委员会批准了CloudEvents作为一个新的独立的CNCF沙箱级项目。 + +## CloudEvents-概念 + +一个[事件](spec.md#事件)包含了[事件发生](spec.md#发生)的上下文和相关数据。 +事件的相关数据可以用来唯一标识一件事件的发生。 + +事件代表了已发生的事实，因此它并不包含任何目的地相关信息，但消息能够传达事件内容，从而将事件数据 +从源头传输到指定的目的地。 + +### 事件使用 + +事件通常在服务器端代码中使用来连接不同的系统，其中一个系统中的状态变化会导致代码在另一个系统中执行。 +比如，一个事件源，可能会在收到某个外部信号(如HTTP或RPC)或观察到状态变化(如IoT传感器数据变化或不活跃) +时，生产一个事件。 + +为了更好地解释一个系统如何使用CloudEvents，下图展示了一个从事件源生产的事件是如何触发一个行为的。 + +![alt text](source-event-action.png "A box representing the source with +arrow pointing to a box representing the action. The arrow is annotated with +'e' for event and 'protocol'.") + +事件源生产了一条封装了基于某种协议的事件数据的消息。 +当载有事件的消息到达目的地时，会触发一个使用了事件数据的行为函数。 + +一个事件源是那些允许暂存和测试实例的源类型的特定实例。 +某个特定源类型的开源软件可能由多个公司或提供商部署。 + +事件可以通过各种行业标准协议（如HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或 +平台/供应商专有协议（AWS Kinesis、Azure Event Grid）传输。 + +一个操作函数能够处理那些定义了行为或影响的事件，这些行为和效果由来自特定源的特定事件触发而来。 +虽然超出了规范的范围，但生成事件的目的通常是让其他系统能够轻松地对它们无法控制的源中的更改做出反应。 +源和操作通常由不同的开发人员构建。 +通常，源是托管服务，而操作是serverless函数（如 AWS Lambda 或 Google Cloud Functions）中 +的自定义代码。 + +## 设计目标 + +CloudEvents 通常用于分布式系统，以允许服务在开发过程中松耦合，独立部署，方便之后连接以创建新的应用程序。 + +CloudEvents 规范的目标是定义允许服务生产或消费事件的事件系统的互操作性， +其中生产者和消费者可以独立开发和部署。 生产者可以在没有消费者监听时就生成事件， +消费者也可以表达对尚未生成的事件或事件类的兴趣。值得注意的是，这项工作产生的规范侧重于事件格式的互操作性 +以及它在通过各种协议（例如 HTTP）发送时的显示方式。我们不关注事件生产者或事件消费者的处理模型。 + +CloudEvents的核心规范中定义了一组称之为属性的元数据， +它们描述了在系统之间传输的事件以及这些元数据片段应如何显示在该消息中。 +这些元数据是，将请求路由到适当组件并帮助该组件正确处理事件所需的最小信息集。 +因此，某些事件本身的数据可能会作为 CloudEvent 属性集的一部分而被复制， +但这样做仅是为了能够正确传递和处理消息。那些不用于该目的的数据应放置在事件（数据）本身中。 + +此外，本规范中假设协议层所需的用来将消息传递到目标系统的元数据应完全由协议处理， +因此不包含在 CloudEvents 属性中。 有关更多详细信息，请参阅[非目标](#非目标)部分。 + +除了这些属性的定义之外，规范还描述了关于如何序列化 +不同格式（例如 JSON）和协议（例如 HTTP、AMQP、Kafka）的事件。 + +一些协议本身支持将多个事件批处理到单个 API 的调用中。 +为了提升系统间的互操作性，是否以及如何实现批处理将由协议自己决定。 +相关详细信息可以在协议绑定或协议规范中找到。 +成批的CloudEvents并没有语义，也没有排序。 +[中间人](spec.md#中间人)可以添加或删除批处理以及将事件分配给不同的批处理。 + +### 非目标 + +以下内容不在本规范的范围之内： + +- 函数的构建和调用过程 +- 特定语言的运行时 APIs +- 选择单一身份认证或访问控制的系统 +- 包含协议级路由信息 +- 事件持久化过程 + +就连那些刚接触 CloudEvents 概念的人都会建议 +CloudEvents 规范不应包括协议级路由信息（例如，将事件发送到的目标的URL）。 +经过深思熟虑，工作组得出的结论是，CloudEvents规范中不需要路由信息： +因为任何现有的协议（例如 HTTP、MQTT、XMPP 或 Pub/Sub 总线）都已经定义了路由语义。 +例如，CloudEvents [HTTP 绑定](http-protocol-binding.md) 规定了头部和请求正文内容。 +CloudEvents 不需要在规范中包含目标 URL 即可与 HTTP 兼容；HTTP 规范已经在 +[请求行](https://tools.ietf.org/html/rfc2616#section-5.1) 中包含了所需的目标URL。 + +路由信息不仅是多余的，而且是有害的。 +CloudEvents 应该增加互操作性并解耦事件的生产者和消费者。 +禁止来自事件格式的路由信息允许将 CloudEvents 重新传送到新的行为，或通过包含多个通道的复杂中继传送。 +例如，如果 Webhook 地址不可用，则用于 Webhook 的 CloudEvent 应可传送到死信队列。 +死信队列应该能够将事件传送给原始事件发射者从未想象过的新的行为上。 + +在系统内和跨系统生产和消费的 CloudEvent能够触发产生价值的行为。 +因此，对于调试或复制的目的而言，存档和或重放事件可能很有价值。 +但是，持久化事件会删除传输期间可用的上下文信息，例如生产者的身份和权利、保真验证机制或机密性保护。 +此外，持久化会增加满足用户需求的复杂性和挑战。 +例如，出于加密或签名目的重复使用私钥会增加攻击者可用的信息，从而降低安全性。 +因此我们推测，可以定义有助于满足持久性要求的属性，但这些属性可能随着行业最佳实践和进步而不断发展。 + +## 架构 +CloudEvents 规范集定义了四种有助于形成分层架构模型的不同类型的协议元素。 +基本规范定义了一个抽象信息模型，该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 + +1. [基本规范](spec.md) 定义了一个抽象信息模型， + 该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 +2. [扩展属性](./spec.md#扩展上下文属性) + 添加了特定于用例且可能重叠的扩展属性集和相关规则，如支持不同的追踪标准的规则。 +3. 事件格式编码,如 [JSON](json-format.md), 定义了基本规范的信息模型与所选扩展的编码方式， + 以将其映射到应用程序协议的头部和负载元素。 +4. 协议绑定, 如. [HTTP协议绑定](http-protocol-binding.md), + 在HTTP to HTTP的情况下， + 定义了 CloudEvent 如何绑定到应用程序协议的传输层 。 + 协议绑定不限制传输层的使用方式，这意味着 HTTP绑定可用于任何 HTTP方法以及请求和响应消息。 + +为了确保更广泛的互操作性，CloudEvents规范集为使用专有应用协议的事件传输提供了特定约束。 +[HTTP Webhook](http-webhook.md)规范并非特定于 CloudEvents， +而是可用于将任何类型的单向事件和通知发布到符合标准的 HTTP 端点。 +但是，由于其他地方缺乏此类规范，因此 CloudEvents 需要对其进行定义。 + +### 协议错误处理 + +CloudEvents 规范在很大程度上并未规定与 CloudEvents 的创建或处理相关联的处理模型。 +因此，如果在处理 CloudEvent 过程中出现错误， +请使用正常的协议级错误处理机制进行处理。 + +## 属性版本控制 + +对于某些 CloudEvents 属性，由其值引用的实体或数据模型可能会随时间变化。 +例如，`dataschema`可能引用模式文档的一个特定版本。 +通常，这些属性值会通过将一些特定于版本的字符串作为其值的一部分来区分每个变体。 +例如，可能会加入版本号 (v1, v2) 或日期 (2018-01-01)来区分。 + +CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强制使用版本字符串。 +是否使用完全取决于每个事件生产者。 +但是，当使用特定版本的字符串时，每当其值发生变化时都应注意， +因为事件消费者可能依赖于现有值，因此更改可能被解释为“破坏性更改”。 +应该在生产者和消费者之间建立某种形式的通信，以确保事件消费者知道能使用哪些可能的值。 +通常，这也适用于所有 CloudEvents 属性。 + +## CloudEvent-属性 + +本节介绍了与CloudEvent 属性相关的其他背景和设计要点。 + +### id + +`id` 属性是一个在同一事件源下所有事件中用来标识事件唯一的值 +（其中每个事件源由其 CloudEvents `source`属性唯一标识）。 +虽然`id`使用的确切值是生产者定义的， +但必须要确保来自单个事件源的 CloudEvents 消费者不会有两个事件共享相同的 id 值。 +唯一的例外是如果支持事件的重播，在这些情况下，可以使用 id 来检测这一点。 + +由于一次事件的发生可能导致生成多个cloud event， +在所有这些事件都来自同一事件源的情况下， +生成的每个 CloudEvent 将具有唯一的 `id`。 +以创建数据库条目为例，这一事件的发生可能会生成一个类型为 create 的 CloudEvent +和一个类型为 write 的 CloudEvent。 +这两个 CloudEvents 各自都有一个唯一的 ID。 +如果需要在这两个 CloudEvent 之间建立某种关联以表明它们都与同一事件相关， +那么可以使用 CloudEvent 中的一些附加数据来实现该目的。 + +从这方面来看，虽然事件生产者对`id`的使用可能是某个随机字符串， +或者在其它上下文中具有某种语义的字符串， +但对于此 CloudEvent 属性而言，这些含义并不成立， +因此本规范不建议将 `id` 用于除了唯一性检查之外的其它目的。 + +## CloudEvent-属性扩展 + +为了实现规范的设计目标， +规范作者将尝试限制他们在 CloudEvents 中定义的元数据属性的数量。 +为此，该项目定义的属性将分为以下三类： + +- 必要属性 +- 可选属性 +- 扩展属性 + +正如类别名称所暗示的那样， +“必要”属性是工作组认为在任何情况下，对所有事件都至关重要的属性， +而“可选”属性将在大多数情况下使用。 这些情况下的两个属性都在本规范中定义了出来。 + +工作组考虑到某些属性不够常见而不能归入上述两个类别， +但此类属性的良好定义仍会使系统间的互操作性级别受益， +因此将这些属性放入了“扩展”类别并记录在[扩展文档](documented-extensions.md)中， +本规范定义了这些扩展属性在 CloudEvent 中的显示方式。 + +在确定提议的属性属于哪个类别时， +工作组使用现有的用例和用户故事来解释它们的基本原理和需求。 +相关信息将添加到本文档的[现有技术](#现有技术)部分。 + +CloudEvent 规范的扩展属性是需要包含的附加元数据，它们能确保正确的路由和正确处理CloudEvent。 +用于其它目的的附加元数据， +即那些与事件本身相但在 CloudEvent 的传输或处理中不需要的元数据， +应改为放置在事件 (`data`)的扩展点内。 + +扩展属性应保持最少，以确保 CloudEvent 可以正确序列化和传输。 +事件生产者应该考虑在向 CloudEvent 添加扩展时可能遇到的技术限制。 +例如，[HTTP Binary Mode](http-protocol-binding.md#31-binary-content-mode) +使用 HTTP 头来传输元数据； +大多数 HTTP 服务器会拒绝包含过多 HTTP 头部数据的请求，要求限制其低至 8kb。 +因此，扩展属性的大小和数量应保持最小。 + +如果扩展变得流行，那么规范作者可能会考虑将其作为核心属性移入规范。 +这意味着在正式将新属性添加到规范之前，扩展机制/过程可用作审查新属性的一种方式。 + +### JSON 扩展 + +如 [CloudEvents JSON 事件格式](json-format.md)中 +[属性](json-format.md#2-attributes)部分所述， +CloudEvent 扩展属性与已定义属性(必要属性、可选属性)在序列化时处于同一等级 - +也就是说，它们都是 JSON 对象的顶层属性。 +CloudEvent的作者花了很长时间考虑所有选项，并认为这是最好的选择。 +理由如下： + +由于CloudEvents规范遵循 [semver](https://semver.org/) ， +这意味着只要新属性是可选属性，它们可以在核心规范的未来版本定义，而无需更改当前主要版本。 +在这样的情况下，请考虑现有消费者将如何使用新的（未知的）顶级属性。 +虽然消费者可以随意忽略它，因为它是可选的， +但在大多数情况下，这些属性仍然希望向接收这些事件的应用程序公开。 +这可能导致这些应用程序在基础设施不支持的情况下，支持这些属性。 +这意味着未知的顶级属性（无论是谁定义的——规范的未来版本或事件生产者）可能不会被忽略。 +因此，虽然其它一些规范定义了放置扩展的特定属性（例如顶级`extensions`属性）， +但作者认为在传入事件中具有两个不同位置的未知属性可能会导致互操作性问题和开发人员的混淆。 + +扩展属性通常用于测试那些被规范正式采用之前的潜在属性。 +如果有一个`extensions`类型的属性，这个新属性已经被序列化， +那么如果该属性被核心规范采用，它将从`extensions`属性提升（从序列化的角度）为顶级属性。 +如果我们假设这个新属性是可选的，那么当它被核心规范采用时， +它只是一个小版本增量，所有现有的消费者仍然会继续工作。 +但是，消费者将不知道此属性将出现在何处 - 在扩展属性中还是作为顶级属性。 +这意味着他们可能需要同时查看两个地方。 +如果属性出现在两个地方但具有不同的值怎么办？ +生产者是否需要将它放在两个地方，因为他们可能同时有新、老消费者？ +虽然可以为如何解决出现的每个潜在问题而制定明确的规则， +但作者认为一个避免这些问题的更好的办法是在序列化中只有一个位置来放置未知的甚至是新的属性。 +作者还注意到 HTTP 规范现在遵循类似的模式，不再建议扩展 HTTP 头部以 X- 为前缀。 + +## 生产CloudEvents + +CloudEvents 规范有意避免将CloudEvents 的创建方式设计的过于死板。 +例如，它不假定原始事件源必须是该事件生产对应 CloudEvent 的同一实体。 +这允许多种实现方式。 +但是，对于规范的实现者来说，理解规范作者心中的期望还是有帮助的，因为这将有助于确保互操作性和一致性。 + +如上所述，生成初始事件的实体是否与创建相应 CloudEvent 的实体相同是由实现决定的。 +但是，当构建/填充 CloudEvents 属性的实体代表事件源进行操作时，这些属性的值是用来描述事件或事件源， +而不是计算 CloudEvent 属性值的实体的。 +换句话说，当事件源和 CloudEvents 生产者之间的分离对事件使用者没有实质性意义时， +规范定义的属性通常不会包含任何值来指示这种职责分离。 + +这并不是说 CloudEvents 生产者不能向 CloudEvent 添加一些额外的属性， +但这些属性超出了规范的互操作性定义属性的范围。 +这类似于 HTTP 代理通常如何最大限度地减少对传入消息的明确定义的 HTTP 头部的更改， +但它可能会添加一些额外的头部，其中包括一些特定代理的元数据。 + +还值得注意的是，原始事件源和 CloudEvents 生产者之间的这种分离可大可小。 +意思是，即使 CloudEvent 生产者不是原始事件源生态系统的一部分， +如果它代表事件源行事，并且它在事件流中的存在对事件消费者没有意义，那么上述指导仍然适用。 + +当实体同时充当 CloudEvents 的接收者和发送者以转发或转换传入事件时， +出站 CloudEvent 与入站 CloudEvent 匹配的程度将根据该实体的处理语义而有所不同。 +在它充当代理的情况下，它只是将 CloudEvents 转发给另一个事件消费者， +那么出站 CloudEvent 通常看起来与入站 CloudEvent 就规范定义的属性相同 +- 请参阅上一段有关添加其他属性的内容。 + +但是，如果此实体正在执行 CloudEvent 的某种类型的语义处理， +通常会导致`data`属性值发生更改， +则可能需要将其视为与原始事件源不同的“事件源”。 +因此，与事件生产者相关的 CloudEvents 属性（例如`source` and `id`） +将从传入的 CloudEvent 中更改。 + +## 合格的协议与编码 + +正如规范中所表达的，CloudEvents 工作的明确目标是 +“以通用方式描述事件数据”且 +“定义允许服务产生或消费事件的事件系统的互操作性，其中生产者和消费者可以被独立开发和部署”。 + +这种互操作性的基础是开放的数据格式和协议， +CloudEvents 旨在提供这种开放的数据格式，并将其数据格式映射到常用协议和常用编码上。 + +虽然每个软件或服务产品和项目都可以自己选择自己喜欢的通信形式， +但毫无疑问，这种产品或项目私有的专有协议无法进一步实现跨生产者和消费者的广泛互操作性的目标。 + +特别是在消息传递和事件处理领域，该行业在过去十年中开发出了强大且受到广泛支持的协议 +例如 HTTP 1.1 和 HTTP/2 以及 WebSockets 或 Web 上的事件，或者 MQTT 和 AMQP +用于面向连接的消息传递和遥测传输的协议。 + +一些广泛使用的协议已经成为事实上的标准，这些协议来自三个或更多公司的顶级财团打造的强大生态系统， +还有一些来自单个公司发布的强大项目生态系统，在任何一种情况下都与前面提到的标准栈的演变相一致。 + +CloudEvents的努力不应成为认可或推广项目或产品专有协议的工具， +因为这与CloudEvents 的原始目标背道而驰。 + +要使协议或编码符合核心 CloudEvents 事件格式或协议绑定的条件，它必须属于以下任一类别： + +- 该协议具有广泛认可的多供应商协议标准化机构（例如 W3C、IETF、OASIS、ISO）的正式标准地位 +- 该协议在其生态系统类别中具有“事实上的标准”地位， + 这意味着它被广泛使用，甚至被认为是给定应用程序的标准。 + 实际上，我们希望在供应商中立的开源组织（例如 Apache、Eclipse、CNCF、.NET 基金会）的保护伞下 + 看到至少一个开源实现， + 并且至少有十几个独立供应商在他们的产品中使用它的产品或服务。 + +除了正式状态之外，协议或编码是否符合核心 CloudEvents 事件格式或协议绑定的一个关键标准是， +该组织是否认为协议或编码出现后，该规范对与产品或项目无关的任何一方具有持续的实际利益。 +对此的基本要求是协议或编码的定义方式允许独立于产品或项目代码的替代实现。 + +欢迎将 CloudEvents 的所有其他协议和编码格式 +包含在指向相应项目自己的公共仓库，或站点中的 CloudEvents binding信息的列表中。 + +## 专有的协议与编码 + +为了鼓励更多人采用 CloudEvents，本仓库将自动收集专有协议和编码。 +本仓库的维护人员不负责创建、维护或通知专有规范的维护人员有关专有规范和CloudEvents规范间的偏差。 + +专有规范将托管在他们自己的仓库或文档站点中，并记录在[专有规范](proprietary-specs.md) +文件中。 专有规范应遵循与核心协议和编码相关的其他规范相同的格式。 + +专有规范将比核心规范受到更少的审查，并且随着 CloudEvents 规范的发展， +相应协议和编码的维护者有责任使规范与 CloudEvents 规范保持同步。 +如果专有规范过时太多，CloudEvents 可能会将指向该规范的链接标记为已弃用或将其删除。 + +如果为同一个协议创建了多个不兼容的规范，存储库维护者将不知道哪个规范是正确的，并列出所有规范的链接。 + +## 现有技术 + +本节介绍了工作组在 CloudEvent 规范开发过程中使用的一些输入材料。 + +### 角色 + +下面列举了可能涉及事件的产生、管理或消费的各种参与者和场景。 + +在这些中，事件生产者和事件消费者的角色是不同的。 +单个应用程序上下文背景始终可以同时承担多个角色，包括既是事件的生产者又是事件的消费者。 + +1. 应用程序生成供他人使用的事件， + 如为消费者提供有关终端用户活动、状态变化或环境观察的见解， + 或允许通过事件驱动的扩展来补充应用程序的功能。 + + 生产的事件通常与上下文或生产者选择的分类相关。 + 例如，房间中的温度传感器可能被安装位置、房间、楼层和建筑物等上下文限定。 + 运动结果可以按联赛和球队分类。 + + 生产者应用程序可以在任何地方运行，例如在服务器或设备上。 + + 生产的事件可能由生产者或中间人直接提供和发出； + 作为后者的示例，请考虑设备通过负载大小受限的网络（如 LoRaWAN 或 ModBus）传输的事件数据， + 并且符合此规范的事件将由网络网关代表生产者提供。 + + 例如，气象站每 5 分钟通过 LoRaWAN 传输一次 12 字节的专有事件payload用于指示天气状况。 + 然后使用 LoRaWAN 网关以 CloudEvents 格式将事件发布到 Internet 目标。 + LoRaWAN 网关是事件生产者，代表气象站发布事件，并将设置一定的元数据以反映事件的来源(气象站)。 + +2. 应用程序可能以以下目的： + 如显示、存档、分析、工作流处理、监控状态或提供业务解决方案及其基本构建模块的透明化 + 来消费事件。 + + 消费者应用程序可以在任何地方运行，例如在服务器或设备上。 + + 消费应用程序通常对以下内容感兴趣： + + - 区分事件，使得完全相同的事件不会被处理两次。 + - 识别和选择源上下文或生产者指定的分类。 + - 确定事件相对于原始上下文或相对于时钟的时间顺序。 + - 了解事件中携带的上下文相关的详细信息。 + - 关联来自多个事件生产者的事件实例并将它们发送到相同的消费者上下文。 + + 在某些情况下，消费应用程序可能对以下内容感兴趣： + + - 从原始上下文中获取有关事件主题的更多详细信息，例如获取有关需要特权访问授权的已更改对象的详细信息。 + 例如，出于隐私原因，HR 解决方案可能仅在事件中发布非常有限的信息， + 任何需要更多数据的事件消费者都必须在其自己的授权上下文背景下从 HR 系统获取与事件相关的详细信息 + - 在原始上下文中与事件的主题进行交互，例如在被告知该数据块刚刚创建后读取存储该数据块。 + + 消费者的兴趣激发了信息生产者应该包括事件的需求。 + +3. 中间件将事件从生产者路由到消费者，或转发到其他中间件。 + 产生事件的应用程序可能会将根据消费者需求产生的某些任务委托给中间件： + + - 管理同时对大量类别和上下文背景中的某个事件感兴趣的消费者。 + - 代表消费者在类或事件的原始上下文上处理过滤条件。 + - 转码，比如从 JSON 解码后在 MsgPack 中编码。 + - 更改事件结构的转换，例如从专有格式映射到 CloudEvents，同时保留事件的身份和语义完整性。 + - 即时“推送式”传输给感兴趣的消费者。 + - 存储最终传输的事件，用于由消费者发起的“拉”请求，或延迟后由中间件发起“推”请求。 + - 观察事件内容或事件流以进行监控或诊断。 + + 为了满足这些需求，中间件将对以下方面感兴趣： + + - 一种元数据鉴别器，可用于事件的分类或上下文化，以便消费者可以表达对一个或多个类或上下文的兴趣。 + 例如，消费者可能对文件存储帐户内的特定目录相关的所有事件感兴趣。 + - 一种元数据鉴别器，允许区分该类或上下文的特定事件的主题。例如，消费者可能希望过滤掉与以“.jpg”结尾的 + 新文件相关的所有事件（文件名是“新文件”事件的主题），以此表示它对感兴趣的文件存储账户下某个目录的 + 上下文环境。 + - 一个事件及其数据编码的指示器。 + - 一个事件及其数据的结构布局（模式）的指示器。 + + 事件是否可通过中间件消费取决于生产者的选择。 + + 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec.md#生产者)的角色， + 当它根据事件采取行动时可以扮演[消费者](spec.md#消费者)的角色， + 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec.md#中间人)的角色。 + +4. 框架和其他抽象使与事件平台基础设施间的交互更简单， + 并且通常为多个事件平台基础设施提供公共 API 区域。 + + 框架通常用于将事件转换为对象图，并将事件分派给某些特定的处理逻辑或用户规则， + 这些用户逻辑或用户规则允许消费应用程序对原始上下文和特定主题中的特定类型的事件做出反应。 + + 框架最感兴趣的是跨抽象平台的语义元数据通用性，以便可以统一处理类似的活动。 + + 对于体育应用程序，使用该框架的开发人员可能对联盟中一支球队今天的比赛（主题） + 的所有事件感兴趣，但希望以不同于“换人”事件的方式处理“得分”事件。 + 为此，框架将需要一个合适的元数据鉴别器，使其不必了解事件细节。 + +### 价值主张 + +本节介绍了一些能够展示 CloudEvents 价值主张的用例。 + +#### 跨服务和平台规范化事件 + +主要事件发布者（例如 AWS、Microsoft、Google 等）都在各自的平台上以不同的格式发布事件。 +甚至在少数情况下，同一提供商的服务以不同格式（例如 AWS）发布事件。 +这迫使事件消费者实现自定义逻辑以跨平台读取或处理事件数据，有时甚至需要跨单个平台的多个服务处理。 + +CloudEvents 可以为那些跨平台和服务处理事件的使用者提供单一体验。 + +#### 促进跨服务和平台的集成 + +跨环境传输的事件数据越来越普遍。 +然而，如果没有描述事件的通用方式，跨环境的事件传递就会受到阻碍。 +CloudEvents之前没有单一的方法可以确定事件的来源和可能的去向。 +这对研究成功传输事件事件工具和消费者知道如何处理事件数据形成了巨大阻碍。 + +CloudEvents 提供有用的元数据，中间件和消费者可以依赖这些元数据来促进事件路由、日志记录、传输和接收。 + +#### 提高功能即服务的可移植性 + +功能即服务（也称为serverless计算）是 IT 中增长最快的趋势之一，它主要是由事件驱动的。 +然而，FaaS 的一个主要问题是供应商锁定。 +这种锁定部分是由函数 API 和供应商之间签名的差异引起的， +锁定同样也是由函数内接收的事件数据格式的差异引起的。 + +CloudEvents提供描述事件数据的通用方式提高了功能即服务的可移植性。 + +#### 改进事件驱动/serverless架构的开发和测试 + +缺乏通用事件格式使事件驱动和serverless架构的开发和测试变得复杂。 +没有简单的方法可以准确地为开发和测试目的模拟事件，并帮助在开发环境中模拟事件驱动的工作流。 + +CloudEvents 可以提供更好的开发工具来构建、测试和处理事件驱动和无服务器架构的端到端生命周期。 + +#### 事件数据发展 + +大多数平台和服务对其事件的数据模型进行不同的版本控制（如果他们这样做的话）。 +随着这些数据模型的发展，这会为发布和使用事件的数据模型带来不一致的体验。 + +CloudEvents 可以提供一种通用的方式来版本化和演化事件数据的发展。 +这将帮助事件发布者根据最佳实践安全地对其数据模型进行版本控制， +并且这有助于事件消费者随着事件数据的发展安全地使用它。 + +#### 规范化 Webhook + +Webhooks 是一种不使用通用格式的来发布事件的模式。 +Webhook 的使用者没有一致的方式来开发、测试、识别、验证和整体处理通过 Webhook 传输的事件数据。 + +CloudEvents 可以提供 Webhook 发布和消费事件的一致性。 + +#### 安全策略 + +出于安全和策略考虑，可能需要过滤、转换或阻止系统之间的事件传输。 +比如可能需要防止事件的进入或退出，如包含敏感信息的事件数据或想要禁止发送方和接收方之间的信息流。 + +通用事件格式将允许更容易地推理正在传输的数据，并提供更好的数据自查。 + +#### 事件追踪 + +从源发送的事件可能会出现在一系列附加事件序列之中， +这些附加事件序列从各种中间件设备（例如事件代理和网关）发出。 +CloudEvents 在事件中包含元数据以将这些事件关联为事件序列的一部分，以便进行事件跟踪和故障排除。 + +#### IoT + +物联网设备会发送和接收与其功能相关的事件。 +例如，连接的恒温器将发送有关当前温度的遥测数据， +并可以接收改变温度的事件。 +这些设备通常具有受限的操作环境（cpu、内存），需要明确定义的事件消息格式。 +在很多情况下，这些消息是二进制编码的，而不是文本的。 +无论是直接来自设备还是通过网关转换，CloudEvents 都可以更好地描述消息的来源和消息中包含的数据格式。 + +#### 事件关联 + +一个serverless应用或工作流可能与来自不同事件源或事件生产者的多个事件相关联。 +例如，盗窃检测应用程序/工作流可能涉及运动事件和门/窗打开事件。 +一个serverless平台可能接收每种类型事件的许多实例，例如 它可以接收来自不同房屋的运动事件和开窗事件。 + +serverless平台需要将一种类型的事件实例与其他类型的事件实例正确关联， +并将接收到的事件实例映射到正确的应用/工作流实例。 +CloudEvents 将为任何事件使用者（例如serverless平台）提供一种标准方式， +以在事件数据中定位事件关联信息/令牌并将接收到的事件实例映射到正确的应用/工作流实例。 + +### 现有的数据格式 + +与上一节一样，对当前现状的调查（和理解）对CloudEvents 小组来说非常重要。 +为此，下面列出了在实践中被广泛使用的当前事件格式的样本。 + +#### Microsoft - Event Grid + +``` +{ + "topic":"/subscriptions/{subscription-id}", + "subject":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/eventSubscriptions/LogicAppdd584bdf-8347-49c9-b9a9-d1f980783501", + "eventType":"Microsoft.Resources.ResourceWriteSuccess", + "eventTime":"2017-08-16T03:54:38.2696833Z", + "id":"25b3b0d0-d79b-44d5-9963-440d4e6a9bba", + "data": { + "authorization":"{azure_resource_manager_authorizations}", + "claims":"{azure_resource_manager_claims}", + "correlationId":"54ef1e39-6a82-44b3-abc1-bdeb6ce4d3c6", + "httpRequest":"", + "resourceProvider":"Microsoft.EventGrid", + "resourceUri":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/eventSubscriptions/LogicAppdd584bdf-8347-49c9-b9a9-d1f980783501", + "operationName":"Microsoft.EventGrid/eventSubscriptions/write", + "status":"Succeeded", + "subscriptionId":"{subscription-id}", + "tenantId":"72f988bf-86f1-41af-91ab-2d7cd011db47" + } +} +``` + +[Documentation](https://docs.microsoft.com/en-us/azure/event-grid/event-schema) + +#### Google - Cloud Functions (potential future) + +``` +{ + "data": { + "@type": "types.googleapis.com/google.pubsub.v1.PubsubMessage", + "attributes": { + "foo": "bar", + }, + "messageId": "12345", + "publishTime": "2017-06-05T12:00:00.000Z", + "data": "somebase64encodedmessage" + }, + "context": { + "eventId": "12345", + "timestamp": "2017-06-05T12:00:00.000Z", + "eventTypeId": "google.pubsub.topic.publish", + "resource": { + "name": "projects/myProject/topics/myTopic", + "service": "pubsub.googleapis.com" + } + } +} +``` + +#### AWS - CloudWatch Events + +AWS 上的很大一部分事件处理系统都在使用这种格式。 + +``` +{ + "version": "0", + "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718", + "detail-type": "EC2 Instance State-change Notification", + "source": "aws.ec2", + "account": "111122223333", + "time": "2017-12-22T18:43:48Z", + "region": "us-west-1", + "resources": [ + "arn:aws:ec2:us-west-1:123456789012:instance/i-1234567890abcdef0" + ], + "detail": { + "instance-id": "i-1234567890abcdef0", + "state": "terminated" + } +} +``` + +#### IBM - OpenWhisk - Web Action Event + +``` +{ + "__ow_method": "post", + "__ow_headers": { + "accept": "*/*", + "connection": "close", + "content-length": "4", + "content-type": "text/plain", + "host": "172.17.0.1", + "user-agent": "curl/7.43.0" + }, + "__ow_path": "", + "__ow_body": "Jane" +} +``` + +#### OpenStack - Audit Middleware - Event + +``` +{ + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + "id": "d8304637-3f63-5092-9ab3-18c9781871a2", + "eventTime": "2018-01-30T10:46:16.740253+00:00", + "action": "delete", + "eventType": "activity", + "outcome": "success", + "reason": { + "reasonType": "HTTP", + "reasonCode": "204" + }, + "initiator": { + "typeURI": "service/security/account/user", + "name": "user1", + "domain": "domain1", + "id": "52d28347f0b4cf9cc1717c00adf41c74cc764fe440b47aacb8404670a7cd5d22", + "host": { + "address": "127.0.0.1", + "agent": "python-novaclient" + }, + "project_id": "ae63ddf2076d4342a56eb049e37a7621" + }, + "target": { + "typeURI": "compute/server", + "id": "b1b475fc-ef0a-4899-87f3-674ac0d56855" + }, + "observer": { + "typeURI": "service/compute", + "name": "nova", + "id": "1b5dbef1-c2e8-5614-888d-bb56bcf65749" + }, + "requestPath": "/v2/ae63ddf2076d4342a56eb049e37a7621/servers/b1b475fc-ef0a-4899-87f3-674ac0d56855" +} +``` + +[Documentation](https://github.com/openstack/pycadf/blob/master/doc/source/event_concept.rst) + +#### Adobe - I/O Events + +``` +{ + "event_id": "639fd17a-d0bb-40ca-83a4-e78612bce5dc", + "event": { + "@id": "82235bac-2b81-4e70-90b5-2bd1f04b5c7b", + "@type": "xdmCreated", + "xdmEventEnvelope:objectType": "xdmAsset", + "activitystreams:to": { + "xdmImsUser:id": "D13A1E7053E46A220A4C86E1@AdobeID", + "@type": "xdmImsUser" + }, + "activitystreams:generator": { + "xdmContentRepository:root": "https://cc-api-storage.adobe.io/", + "@type": "xdmContentRepository" + }, + "activitystreams:actor": { + "xdmImsUser:id": "D13A1E7053E46A220A4C86E1@AdobeID", + "@type": "xdmImsUser" + }, + "activitystreams:object": { + "@type": "xdmAsset", + "xdmAsset:asset_id": "urn:aaid:sc:us:4123ba4c-93a8-4c5d-b979-ffbbe4318185", + "xdmAsset:asset_name": "example.jpg", + "xdmAsset:etag": "6fc55d0389d856ae7deccebba54f110e", + "xdmAsset:path": "/MyFolder/example.jpg", + "xdmAsset:format": "image/jpeg" + }, + "activitystreams:published": "2016-07-16T19:20:30+01:00" + } +} +``` + +[Documentation](https://www.adobe.io/apis/cloudplatform/events/documentation.html) From c7ec4eb7bbff6563e5b338814eedfa7e31e1af2f Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:27:32 +0800 Subject: [PATCH 49/60] Update primer.md Signed-off-by: JieDing --- primer.md | 1219 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 706 insertions(+), 513 deletions(-) diff --git a/primer.md b/primer.md index a5382f71f..367262195 100644 --- a/primer.md +++ b/primer.md @@ -1,539 +1,731 @@ -# CloudEvents 入门文档 - 1.0 版本 - -Declaration： This manual aims to provide a fast and brief introduction of CloudEvents -in Chinese for people who are new to CloudEvents. -Most of the content is translated from the original English version. -It is strongly recommended to read the English version if you find anything lost in translation. - -## 摘要 - -这份非技术规范文档用来为你提供关于CloudEvents规范的总体概览。它补充了CloudEvents规范的相关背景 -以及在制定 本规范时的历史和设计理念。这样，CloudEvents的核心规范就只需要关注Events规范的技术细节， -而不用过多地关心背景相关内容。 - -## 目录 - -- [历史](#历史) -- [CloudEvents 概念](#CloudEvents-概念) -- [设计目标](#设计目标) -- [架构](#架构) -- [属性版本控制](#属性版本控制) -- [CloudEvent 属性](#CloudEvent-属性) -- [CloudEvent 属性扩展](#CloudEvent-属性扩展) -- [生产 CloudEvents](#生产CloudEvents) -- [合格的协议与编码](#合格的协议与编码) -- [专有的协议和编码](#专有的协议与编码) -- [现有技术](#现有技术) -- [角色](#角色) -- [价值主张](#价值主张) -- [现有的数据格式](#现有的数据格式) - -## 历史 - -[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 是由 CNCF的 -[技术监管委员会](https://github.com/cncf/toc) 成立，用于研究 -Serverless相关技术并为CNCF推荐相关领域的未来发展计划的。工作组其中一项建议就是研究创建一种通用事件格式， -用于提升不同云厂商间函数的可移植性和事件流处理的互操作性。就此，CloudEvents应运而生。 - -尽管CloudEvents起初是作为Serverless工作组的项目进行的，但随着CloudEvents规范完成它v0.1版本的里程碑， -技术监管委员会批准了CloudEvents作为一个新的独立的CNCF沙箱级项目。 - -## CloudEvents-概念 - -一个[事件](spec.md#事件)包含了[事件发生](spec.md#发生)的上下文和相关数据。 -事件的相关数据可以用来唯一标识一件事件的发生。 - -事件代表了已发生的事实，因此它并不包含任何目的地相关信息，但消息能够传达事件内容，从而将事件数据 -从源头传输到指定的目的地。 - -### 事件使用 - -事件通常在服务器端代码中使用来连接不同的系统，其中一个系统中的状态变化会导致代码在另一个系统中执行。 -比如，一个事件源，可能会在收到某个外部信号(如HTTP或RPC)或观察到状态变化(如IoT传感器数据变化或不活跃) -时，生产一个事件。 - -为了更好地解释一个系统如何使用CloudEvents，下图展示了一个从事件源生产的事件是如何触发一个行为的。 +# CloudEvents Primer - Version 1.0 + +## Abstract + +This non-normative document provides an overview of the CloudEvents +specification. It is meant to complement the CloudEvent specification to provide +additional background and insight into the history and design decisions made +during the development of the specification. This allows the specification +itself to focus on the normative technical details. + +## Table of Contents + +- [History](#history) +- [CloudEvents Concepts](#cloudevents-concepts) +- [Design Goals](#design-goals) +- [Architecture](#architecture) +- [Versioning of Attributes](#versioning-of-attributes) +- [CloudEvent Attributes](#cloudevent-attributes) +- [CloudEvent Attribute Extensions](#cloudevent-attribute-extensions) +- [Creating CloudEvents](#creating-cloudevents) +- [Qualifying Protocols and Encodings](#qualifying-protocols-and-encodings) +- [Proprietary Protocols and Encodings](#proprietary-protocols-and-encodings) +- [Prior Art](#prior-art) +- [Roles](#roles) +- [Value Proposition](#value-proposition) +- [Existing Event Formats](#existing-event-formats) + +## History + +The [CNCF Serverless Working group](https://github.com/cncf/wg-serverless) was +originally created by the CNCF's +[Technical Oversight Committee](https://github.com/cncf/toc) to investigate +Serverless Technology and to recommend some possible next steps for some CNCF +related activities in this space. One of the recommendations was to investigate +the creation of a common event format to aid in the portability of functions +between Cloud providers and the interoperability of processing of event streams. +As a result, the CloudEvents specification was created. + +While initially the work on CloudEvents was done as part of the Serverless +Working group, once the specification reached its v0.1 milestone, the TOC +approved the CloudEvents work as a new stand-alone CNCF sandbox project. + +## CloudEvents Concepts + +An [event](spec.md#event) includes context and data about an +[occurrence](spec.md#occurrence). Each _occurrence_ is uniquely identified by +the data of the _event_. + +_Events_ represent facts and therefore do not include a destination, whereas +messages convey intent, transporting data from a source to a given destination. + +### Eventing + +Events are commonly used in server-side code to connect disparate systems where +the change of state in one system causes code to execute in another. For +example, a source may generate an event when it receives an external signal +(e.g. HTTP or RPC) or observes a changing value (e.g. an IoT sensor or period of +inactivity). + +To illustrate how a system uses CloudEvents, the simplified diagram below shows +how an event from a [source](spec.md#source) triggers an action. ![alt text](source-event-action.png "A box representing the source with arrow pointing to a box representing the action. The arrow is annotated with 'e' for event and 'protocol'.") -事件源生产了一条封装了基于某种协议的事件数据的消息。 -当载有事件的消息到达目的地时，会触发一个使用了事件数据的行为函数。 - -一个事件源是那些允许暂存和测试实例的源类型的特定实例。 -某个特定源类型的开源软件可能由多个公司或提供商部署。 - -事件可以通过各种行业标准协议（如HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或 -平台/供应商专有协议（AWS Kinesis、Azure Event Grid）传输。 - -一个操作函数能够处理那些定义了行为或影响的事件，这些行为和效果由来自特定源的特定事件触发而来。 -虽然超出了规范的范围，但生成事件的目的通常是让其他系统能够轻松地对它们无法控制的源中的更改做出反应。 -源和操作通常由不同的开发人员构建。 -通常，源是托管服务，而操作是serverless函数（如 AWS Lambda 或 Google Cloud Functions）中 -的自定义代码。 - -## 设计目标 - -CloudEvents 通常用于分布式系统，以允许服务在开发过程中松耦合，独立部署，方便之后连接以创建新的应用程序。 - -CloudEvents 规范的目标是定义允许服务生产或消费事件的事件系统的互操作性， -其中生产者和消费者可以独立开发和部署。 生产者可以在没有消费者监听时就生成事件， -消费者也可以表达对尚未生成的事件或事件类的兴趣。值得注意的是，这项工作产生的规范侧重于事件格式的互操作性 -以及它在通过各种协议（例如 HTTP）发送时的显示方式。我们不关注事件生产者或事件消费者的处理模型。 - -CloudEvents的核心规范中定义了一组称之为属性的元数据， -它们描述了在系统之间传输的事件以及这些元数据片段应如何显示在该消息中。 -这些元数据是，将请求路由到适当组件并帮助该组件正确处理事件所需的最小信息集。 -因此，某些事件本身的数据可能会作为 CloudEvent 属性集的一部分而被复制， -但这样做仅是为了能够正确传递和处理消息。那些不用于该目的的数据应放置在事件（数据）本身中。 - -此外，本规范中假设协议层所需的用来将消息传递到目标系统的元数据应完全由协议处理， -因此不包含在 CloudEvents 属性中。 有关更多详细信息，请参阅[非目标](#非目标)部分。 - -除了这些属性的定义之外，规范还描述了关于如何序列化 -不同格式（例如 JSON）和协议（例如 HTTP、AMQP、Kafka）的事件。 - -一些协议本身支持将多个事件批处理到单个 API 的调用中。 -为了提升系统间的互操作性，是否以及如何实现批处理将由协议自己决定。 -相关详细信息可以在协议绑定或协议规范中找到。 -成批的CloudEvents并没有语义，也没有排序。 -[中间人](spec.md#中间人)可以添加或删除批处理以及将事件分配给不同的批处理。 - -### 非目标 - -以下内容不在本规范的范围之内： - -- 函数的构建和调用过程 -- 特定语言的运行时 APIs -- 选择单一身份认证或访问控制的系统 -- 包含协议级路由信息 -- 事件持久化过程 - -就连那些刚接触 CloudEvents 概念的人都会建议 -CloudEvents 规范不应包括协议级路由信息（例如，将事件发送到的目标的URL）。 -经过深思熟虑，工作组得出的结论是，CloudEvents规范中不需要路由信息： -因为任何现有的协议（例如 HTTP、MQTT、XMPP 或 Pub/Sub 总线）都已经定义了路由语义。 -例如，CloudEvents [HTTP 绑定](http-protocol-binding.md) 规定了头部和请求正文内容。 -CloudEvents 不需要在规范中包含目标 URL 即可与 HTTP 兼容；HTTP 规范已经在 -[请求行](https://tools.ietf.org/html/rfc2616#section-5.1) 中包含了所需的目标URL。 - -路由信息不仅是多余的，而且是有害的。 -CloudEvents 应该增加互操作性并解耦事件的生产者和消费者。 -禁止来自事件格式的路由信息允许将 CloudEvents 重新传送到新的行为，或通过包含多个通道的复杂中继传送。 -例如，如果 Webhook 地址不可用，则用于 Webhook 的 CloudEvent 应可传送到死信队列。 -死信队列应该能够将事件传送给原始事件发射者从未想象过的新的行为上。 - -在系统内和跨系统生产和消费的 CloudEvent能够触发产生价值的行为。 -因此，对于调试或复制的目的而言，存档和或重放事件可能很有价值。 -但是，持久化事件会删除传输期间可用的上下文信息，例如生产者的身份和权利、保真验证机制或机密性保护。 -此外，持久化会增加满足用户需求的复杂性和挑战。 -例如，出于加密或签名目的重复使用私钥会增加攻击者可用的信息，从而降低安全性。 -因此我们推测，可以定义有助于满足持久性要求的属性，但这些属性可能随着行业最佳实践和进步而不断发展。 - -## 架构 -CloudEvents 规范集定义了四种有助于形成分层架构模型的不同类型的协议元素。 -基本规范定义了一个抽象信息模型，该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 - -1. [基本规范](spec.md) 定义了一个抽象信息模型， - 该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 -2. [扩展属性](./spec.md#扩展上下文属性) - 添加了特定于用例且可能重叠的扩展属性集和相关规则，如支持不同的追踪标准的规则。 -3. 事件格式编码,如 [JSON](json-format.md), 定义了基本规范的信息模型与所选扩展的编码方式， - 以将其映射到应用程序协议的头部和负载元素。 -4. 协议绑定, 如. [HTTP协议绑定](http-protocol-binding.md), - 在HTTP to HTTP的情况下， - 定义了 CloudEvent 如何绑定到应用程序协议的传输层 。 - 协议绑定不限制传输层的使用方式，这意味着 HTTP绑定可用于任何 HTTP方法以及请求和响应消息。 - -为了确保更广泛的互操作性，CloudEvents规范集为使用专有应用协议的事件传输提供了特定约束。 -[HTTP Webhook](http-webhook.md)规范并非特定于 CloudEvents， -而是可用于将任何类型的单向事件和通知发布到符合标准的 HTTP 端点。 -但是，由于其他地方缺乏此类规范，因此 CloudEvents 需要对其进行定义。 - -### 协议错误处理 - -CloudEvents 规范在很大程度上并未规定与 CloudEvents 的创建或处理相关联的处理模型。 -因此，如果在处理 CloudEvent 过程中出现错误， -请使用正常的协议级错误处理机制进行处理。 - -## 属性版本控制 - -对于某些 CloudEvents 属性，由其值引用的实体或数据模型可能会随时间变化。 -例如，`dataschema`可能引用模式文档的一个特定版本。 -通常，这些属性值会通过将一些特定于版本的字符串作为其值的一部分来区分每个变体。 -例如，可能会加入版本号 (v1, v2) 或日期 (2018-01-01)来区分。 - -CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强制使用版本字符串。 -是否使用完全取决于每个事件生产者。 -但是，当使用特定版本的字符串时，每当其值发生变化时都应注意， -因为事件消费者可能依赖于现有值，因此更改可能被解释为“破坏性更改”。 -应该在生产者和消费者之间建立某种形式的通信，以确保事件消费者知道能使用哪些可能的值。 -通常，这也适用于所有 CloudEvents 属性。 - -## CloudEvent-属性 - -本节介绍了与CloudEvent 属性相关的其他背景和设计要点。 +The source generates a message where the event is encapsulated in a protocol. +The event arrives to a destination, triggering an action which is provided with +the event data. + +A _source_ is a specific instance of a source-type which allows for staging and +test instances. Open source software of a specific _source-type_ may be deployed +by multiple companies or providers. + +Events can be delivered through various industry standard protocols (e.g. HTTP, +AMQP, MQTT, SMTP), open-source protocols (e.g. Kafka, NATS), or platform/vendor +specific protocols (AWS Kinesis, Azure Event Grid). + +An action processes an event defining a behavior or effect which was triggered +by a specific _occurrence_ from a specific _source_. While outside of the scope +of the specification, the purpose of generating an _event_ is typically to allow +other systems to easily react to changes in a source that they do not control. +The _source_ and action are typically built by different developers. Often the +_source_ is a managed service and the _action_ is custom code in a serverless +Function (such as AWS Lambda or Google Cloud Functions). + +## Design Goals + +CloudEvents are typically used in a distributed system to allow for services to +be loosely coupled during development, deployed independently, and later can be +connected to create new applications. + +The goal of the CloudEvents specification is to define interoperability of event +systems that allow services to produce or consume events, where the producer and +consumer can be developed and deployed independently. A producer can generate +events before a consumer is listening, and a consumer can express an interest in +an event or class of events that is not yet being produced. Note that the +specifications produced by this effort are focused on interoperability of the +event format and how it appears while being sent on various protocols, such as +HTTP. The specifications will not focus on the processing model of either the +event producer or event consumer. + +CloudEvents, at its core, defines a set of metadata, called attributes, about +the event being transferred between systems, and how those pieces of metadata +should appear in that message. This metadata is meant to be the minimal set of +information needed to route the request to the proper component and to +facilitate proper processing of the event by that component. So, while this +might mean that some of the application data of the event itself might be +duplicated as part of the CloudEvent's set of attributes, this is to be done +solely for the purpose of proper delivery, and processing, of the message. Data +that is not intended for that purpose should instead be placed within the event +(`data`) itself. + +Additionally, it is assumed that the metadata needed by the protocol layer to +deliver the message to the target system is handled entirely by the protocol +and therefore is not included within the CloudEvents attributes. See the +[Non-Goals](#non-goals) section for more details. + +Along with the definition of these attributes, there will also be specifications +of how to serialize the event in different formats (e.g. JSON) and protocols +(e.g. HTTP, AMQP, Kafka). + +Batching of multiple events into a single API call is natively supported by some +protocols. To aid interoperability, it is left up to the protocols if and how +batching is implemented. Details may be found in the protocol binding or in the +protocol specification. A batch of CloudEvents carries no semantic meaning and +is not ordered. An [Intermediary](spec.md#intermediary) can add or remove +batching as well as assign events to different batches. + +### Non-Goals + +The following are considered beyond the scope of the specification: + +- Function build and invocation process +- Language-specific runtime APIs +- Selecting a single identity/access control system +- Inclusion of protocol-level routing information +- Event persistence processes + +The CloudEvents spec will not include protocol-level routing information (e.g. +a destination URL to which the event is being sent). This is a common suggestion +by those new to the concepts of CloudEvents. After much deliberation, the +working group has come to the conclusion that routing is unnecessary in the +spec: any protocol (e.g. HTTP, MQTT, XMPP, or a Pub/Sub bus) already +defines semantics for routing. For example, the CloudEvents +[HTTP binding](http-protocol-binding.md) dictates headers and request body +contents. CloudEvents don't need to include a destination URL in the spec to be +HTTP compatible; the HTTP spec already includes one in the +[Request-Line](https://tools.ietf.org/html/rfc2616#section-5.1). + +Routing information is not just redundant, it detracts. CloudEvents should +increase interoperability and decouple the producer and consumer of events. +Prohibiting routing information from the events format allows CloudEvents to be +redelivered to new actions, or to be delivered over complex relays that include +multiple channels. For example, a CloudEvent that was intended for a webhook +should be deliverable to a dead-letter queue if the webhook address is +unavailable. That dead-letter queue should be able to feed events to new actions +that the original event emitter never imagined. + +The CloudEvents that are produced and consumed within and across systems trigger +behaviors that derive value. As such, archiving and/or replaying events can be +valuable for debugging or replication purposes. However, persisting an event +removes the contextual information available during transmission such as the +identity and rights of the producer, fidelity validation mechanisms, or +confidentiality protections. Additionally, persistence can add complexity and +challenge to meeting user's requirements. For example, the repeated use of a +private key for encryption or signing purposes increases the information +available to attackers and thereby reduces security. It is expected that +attributes may be defined that facilitate meeting persistence requirements but +it is expected that these will continuously evolve along with industry best +practices and advancements. + +## Architecture + +The CloudEvents specification set defines four different kinds of protocol +elements that form a layered architecture model. + +1. The [base specification](spec.md) defines an abstract information model made + up of attributes (key-value pairs) and associated rules for what constitutes + a CloudEvent. +2. The [extensions](./spec.md#extension-context-attributes) add use-case + specific and potentially overlapping sets of extension attributes and + associated rules, e.g. to support different tracing standards. +3. The event format encodings, e.g. [JSON](json-format.md), define how the + information model of the base specification together with the chosen + extensions is encoded for mapping it to header and payload elements of an + application protocol. +4. The protocol bindings, e.g. [HTTP](http-protocol-binding.md), defines how + the CloudEvent is bound to an application protocol's transport frame, in the + case of HTTP to the HTTP message. The protocol binding does not constrain + how the transport frame is used, meaning that the HTTP binding can be used + with any HTTP method and with request and response messages. + +If required to assure broader interoperability, the CloudEvents specification +set provides specific constraints for event delivery using a particular +application protocol. The [HTTP Webhook](http-webhook.md) specification is not +specific to CloudEvents and can be used to post any kind of one-way event and +notifications to a conformant HTTP endpoint. However, the lack of such a +specification elsewhere makes it necessary for CloudEvents to define it. + +### Protocol Error Handling + +The CloudEvents specification, for the most part, does not dictate a processing +model associated with the creation or processing of CloudEvents. As such, if +there are errors during the processing of a CloudEvent, the software +encountering the error is encouraged to use the normal protocol-level error +reporting to report them. + +## Versioning of Attributes + +For certain CloudEvents attributes, the entity or data model referenced by its +value might change over time. For example, `dataschema` might reference one +particular version of a schema document. Often these attribute values will then +distinguish each variant by including some version-specific string as part of +its value. For example, a version number (`v1`, `v2`), or a date (`2018-01-01`) +might be used. + +The CloudEvents specification does not mandate any particular pattern to be +used, or even the use of version strings at all. This decision is up to each +event producer. However, when a version-specific string is included, care should +be taken whenever its value changes as event consumers might be reliant on the +existing value and thus a change could be interpreted as a "breaking change". +Some form of communication between producers and consumers should be established +to ensure the event consumers know what possible values might be used. In +general, this is true for all CloudEvents attributes as well. + +## CloudEvent Attributes + +This section provides additional background and design points related to some of +the CloudEvent attributes. ### id -`id` 属性是一个在同一事件源下所有事件中用来标识事件唯一的值 -（其中每个事件源由其 CloudEvents `source`属性唯一标识）。 -虽然`id`使用的确切值是生产者定义的， -但必须要确保来自单个事件源的 CloudEvents 消费者不会有两个事件共享相同的 id 值。 -唯一的例外是如果支持事件的重播，在这些情况下，可以使用 id 来检测这一点。 - -由于一次事件的发生可能导致生成多个cloud event， -在所有这些事件都来自同一事件源的情况下， -生成的每个 CloudEvent 将具有唯一的 `id`。 -以创建数据库条目为例，这一事件的发生可能会生成一个类型为 create 的 CloudEvent -和一个类型为 write 的 CloudEvent。 -这两个 CloudEvents 各自都有一个唯一的 ID。 -如果需要在这两个 CloudEvent 之间建立某种关联以表明它们都与同一事件相关， -那么可以使用 CloudEvent 中的一些附加数据来实现该目的。 - -从这方面来看，虽然事件生产者对`id`的使用可能是某个随机字符串， -或者在其它上下文中具有某种语义的字符串， -但对于此 CloudEvent 属性而言，这些含义并不成立， -因此本规范不建议将 `id` 用于除了唯一性检查之外的其它目的。 - -## CloudEvent-属性扩展 - -为了实现规范的设计目标， -规范作者将尝试限制他们在 CloudEvents 中定义的元数据属性的数量。 -为此，该项目定义的属性将分为以下三类： - -- 必要属性 -- 可选属性 -- 扩展属性 - -正如类别名称所暗示的那样， -“必要”属性是工作组认为在任何情况下，对所有事件都至关重要的属性， -而“可选”属性将在大多数情况下使用。 这些情况下的两个属性都在本规范中定义了出来。 - -工作组考虑到某些属性不够常见而不能归入上述两个类别， -但此类属性的良好定义仍会使系统间的互操作性级别受益， -因此将这些属性放入了“扩展”类别并记录在[扩展文档](documented-extensions.md)中， -本规范定义了这些扩展属性在 CloudEvent 中的显示方式。 - -在确定提议的属性属于哪个类别时， -工作组使用现有的用例和用户故事来解释它们的基本原理和需求。 -相关信息将添加到本文档的[现有技术](#现有技术)部分。 - -CloudEvent 规范的扩展属性是需要包含的附加元数据，它们能确保正确的路由和正确处理CloudEvent。 -用于其它目的的附加元数据， -即那些与事件本身相但在 CloudEvent 的传输或处理中不需要的元数据， -应改为放置在事件 (`data`)的扩展点内。 - -扩展属性应保持最少，以确保 CloudEvent 可以正确序列化和传输。 -事件生产者应该考虑在向 CloudEvent 添加扩展时可能遇到的技术限制。 -例如，[HTTP Binary Mode](http-protocol-binding.md#31-binary-content-mode) -使用 HTTP 头来传输元数据； -大多数 HTTP 服务器会拒绝包含过多 HTTP 头部数据的请求，要求限制其低至 8kb。 -因此，扩展属性的大小和数量应保持最小。 - -如果扩展变得流行，那么规范作者可能会考虑将其作为核心属性移入规范。 -这意味着在正式将新属性添加到规范之前，扩展机制/过程可用作审查新属性的一种方式。 - -### JSON 扩展 - -如 [CloudEvents JSON 事件格式](json-format.md)中 -[属性](json-format.md#2-attributes)部分所述， -CloudEvent 扩展属性与已定义属性(必要属性、可选属性)在序列化时处于同一等级 - -也就是说，它们都是 JSON 对象的顶层属性。 -CloudEvent的作者花了很长时间考虑所有选项，并认为这是最好的选择。 -理由如下： - -由于CloudEvents规范遵循 [semver](https://semver.org/) ， -这意味着只要新属性是可选属性，它们可以在核心规范的未来版本定义，而无需更改当前主要版本。 -在这样的情况下，请考虑现有消费者将如何使用新的（未知的）顶级属性。 -虽然消费者可以随意忽略它，因为它是可选的， -但在大多数情况下，这些属性仍然希望向接收这些事件的应用程序公开。 -这可能导致这些应用程序在基础设施不支持的情况下，支持这些属性。 -这意味着未知的顶级属性（无论是谁定义的——规范的未来版本或事件生产者）可能不会被忽略。 -因此，虽然其它一些规范定义了放置扩展的特定属性（例如顶级`extensions`属性）， -但作者认为在传入事件中具有两个不同位置的未知属性可能会导致互操作性问题和开发人员的混淆。 - -扩展属性通常用于测试那些被规范正式采用之前的潜在属性。 -如果有一个`extensions`类型的属性，这个新属性已经被序列化， -那么如果该属性被核心规范采用，它将从`extensions`属性提升（从序列化的角度）为顶级属性。 -如果我们假设这个新属性是可选的，那么当它被核心规范采用时， -它只是一个小版本增量，所有现有的消费者仍然会继续工作。 -但是，消费者将不知道此属性将出现在何处 - 在扩展属性中还是作为顶级属性。 -这意味着他们可能需要同时查看两个地方。 -如果属性出现在两个地方但具有不同的值怎么办？ -生产者是否需要将它放在两个地方，因为他们可能同时有新、老消费者？ -虽然可以为如何解决出现的每个潜在问题而制定明确的规则， -但作者认为一个避免这些问题的更好的办法是在序列化中只有一个位置来放置未知的甚至是新的属性。 -作者还注意到 HTTP 规范现在遵循类似的模式，不再建议扩展 HTTP 头部以 X- 为前缀。 - -## 生产CloudEvents - -CloudEvents 规范有意避免将CloudEvents 的创建方式设计的过于死板。 -例如，它不假定原始事件源必须是该事件生产对应 CloudEvent 的同一实体。 -这允许多种实现方式。 -但是，对于规范的实现者来说，理解规范作者心中的期望还是有帮助的，因为这将有助于确保互操作性和一致性。 - -如上所述，生成初始事件的实体是否与创建相应 CloudEvent 的实体相同是由实现决定的。 -但是，当构建/填充 CloudEvents 属性的实体代表事件源进行操作时，这些属性的值是用来描述事件或事件源， -而不是计算 CloudEvent 属性值的实体的。 -换句话说，当事件源和 CloudEvents 生产者之间的分离对事件使用者没有实质性意义时， -规范定义的属性通常不会包含任何值来指示这种职责分离。 - -这并不是说 CloudEvents 生产者不能向 CloudEvent 添加一些额外的属性， -但这些属性超出了规范的互操作性定义属性的范围。 -这类似于 HTTP 代理通常如何最大限度地减少对传入消息的明确定义的 HTTP 头部的更改， -但它可能会添加一些额外的头部，其中包括一些特定代理的元数据。 - -还值得注意的是，原始事件源和 CloudEvents 生产者之间的这种分离可大可小。 -意思是，即使 CloudEvent 生产者不是原始事件源生态系统的一部分， -如果它代表事件源行事，并且它在事件流中的存在对事件消费者没有意义，那么上述指导仍然适用。 - -当实体同时充当 CloudEvents 的接收者和发送者以转发或转换传入事件时， -出站 CloudEvent 与入站 CloudEvent 匹配的程度将根据该实体的处理语义而有所不同。 -在它充当代理的情况下，它只是将 CloudEvents 转发给另一个事件消费者， -那么出站 CloudEvent 通常看起来与入站 CloudEvent 就规范定义的属性相同 -- 请参阅上一段有关添加其他属性的内容。 - -但是，如果此实体正在执行 CloudEvent 的某种类型的语义处理， -通常会导致`data`属性值发生更改， -则可能需要将其视为与原始事件源不同的“事件源”。 -因此，与事件生产者相关的 CloudEvents 属性（例如`source` and `id`） -将从传入的 CloudEvent 中更改。 - -## 合格的协议与编码 - -正如规范中所表达的，CloudEvents 工作的明确目标是 -“以通用方式描述事件数据”且 -“定义允许服务产生或消费事件的事件系统的互操作性，其中生产者和消费者可以被独立开发和部署”。 - -这种互操作性的基础是开放的数据格式和协议， -CloudEvents 旨在提供这种开放的数据格式，并将其数据格式映射到常用协议和常用编码上。 - -虽然每个软件或服务产品和项目都可以自己选择自己喜欢的通信形式， -但毫无疑问，这种产品或项目私有的专有协议无法进一步实现跨生产者和消费者的广泛互操作性的目标。 - -特别是在消息传递和事件处理领域，该行业在过去十年中开发出了强大且受到广泛支持的协议 -例如 HTTP 1.1 和 HTTP/2 以及 WebSockets 或 Web 上的事件，或者 MQTT 和 AMQP -用于面向连接的消息传递和遥测传输的协议。 - -一些广泛使用的协议已经成为事实上的标准，这些协议来自三个或更多公司的顶级财团打造的强大生态系统， -还有一些来自单个公司发布的强大项目生态系统，在任何一种情况下都与前面提到的标准栈的演变相一致。 - -CloudEvents的努力不应成为认可或推广项目或产品专有协议的工具， -因为这与CloudEvents 的原始目标背道而驰。 - -要使协议或编码符合核心 CloudEvents 事件格式或协议绑定的条件，它必须属于以下任一类别： - -- 该协议具有广泛认可的多供应商协议标准化机构（例如 W3C、IETF、OASIS、ISO）的正式标准地位 -- 该协议在其生态系统类别中具有“事实上的标准”地位， - 这意味着它被广泛使用，甚至被认为是给定应用程序的标准。 - 实际上，我们希望在供应商中立的开源组织（例如 Apache、Eclipse、CNCF、.NET 基金会）的保护伞下 - 看到至少一个开源实现， - 并且至少有十几个独立供应商在他们的产品中使用它的产品或服务。 - -除了正式状态之外，协议或编码是否符合核心 CloudEvents 事件格式或协议绑定的一个关键标准是， -该组织是否认为协议或编码出现后，该规范对与产品或项目无关的任何一方具有持续的实际利益。 -对此的基本要求是协议或编码的定义方式允许独立于产品或项目代码的替代实现。 - -欢迎将 CloudEvents 的所有其他协议和编码格式 -包含在指向相应项目自己的公共仓库，或站点中的 CloudEvents binding信息的列表中。 - -## 专有的协议与编码 - -为了鼓励更多人采用 CloudEvents，本仓库将自动收集专有协议和编码。 -本仓库的维护人员不负责创建、维护或通知专有规范的维护人员有关专有规范和CloudEvents规范间的偏差。 - -专有规范将托管在他们自己的仓库或文档站点中，并记录在[专有规范](proprietary-specs.md) -文件中。 专有规范应遵循与核心协议和编码相关的其他规范相同的格式。 - -专有规范将比核心规范受到更少的审查，并且随着 CloudEvents 规范的发展， -相应协议和编码的维护者有责任使规范与 CloudEvents 规范保持同步。 -如果专有规范过时太多，CloudEvents 可能会将指向该规范的链接标记为已弃用或将其删除。 - -如果为同一个协议创建了多个不兼容的规范，存储库维护者将不知道哪个规范是正确的，并列出所有规范的链接。 - -## 现有技术 - -本节介绍了工作组在 CloudEvent 规范开发过程中使用的一些输入材料。 - -### 角色 - -下面列举了可能涉及事件的产生、管理或消费的各种参与者和场景。 - -在这些中，事件生产者和事件消费者的角色是不同的。 -单个应用程序上下文背景始终可以同时承担多个角色，包括既是事件的生产者又是事件的消费者。 - -1. 应用程序生成供他人使用的事件， - 如为消费者提供有关终端用户活动、状态变化或环境观察的见解， - 或允许通过事件驱动的扩展来补充应用程序的功能。 +The `id` attribute is meant to be a value that is unique across all events +related to one event source (where each event source is uniquely identified by +its CloudEvents `source` attribute value). While the exact value used is +producer defined, receivers of CloudEvents from a single event source can be +assured that no two events will share the same `id` value. The only exception to +this is if some replay of the event is supported, and in those cases, the `id` +can then be used to detect this. + +Since a single occurrence may result in the generation of more than one event, +in the cases where all of those events are from the same event source, each +CloudEvent constructed will have a unique `id`. Take the example of the creation +of a DB entry, this one occurrence might generate a CloudEvent with a type of +`create` and a CloudEvent with a type of `write`. Each of those CloudEvents +would have a unique `id`. If there is the desire for some correlation between +those two CloudEvents to indicate they are both related to the same occurrence, +then some additional data within the CloudEvent would be used for that purpose. + +In this respect, while the exact value chosen by the event producer might be +some random string, or a string that has some semantic meaning in some other +context, for the purposes of this CloudEvent attribute those meanings are not +relevant and therefore using `id` for some other purpose beyond uniqueness +checking is out of scope of the specification and not recommended. + +## CloudEvent Attribute Extensions + +In order to achieve the stated goals, the specification authors will attempt to +constrain the number of metadata attributes they define in CloudEvents. To that +end, attributes defined by this project will fall into three categories: + +- required +- optional +- extensions + +As the category names imply, "required" attributes will be the ones that the +group considers vital to all events in all use cases, while "optional" ones will +be used in a majority of the cases. Both of the attributes in these cases will +be defined within the specification itself. + +When the group determines that an attribute is not common enough to fall into +those two categories but would still benefit from the level of interoperability +that comes from being well-defined, then they will be placed into the +"extensions" category and put into +[documented extensions](documented-extensions.md). The specification defines how +these extension attributes will appear within a CloudEvent. + +In determining which category a proposed attribute belongs, or even if it will +be included at all, the group uses use-cases and user-stories to explain the +rationale and need for them. This supporting information will be added to the +[Prior Art](#prior-art) section of this document. + +Extension attributes to the CloudEvent specification are meant to be additional +metadata that needs to be included to help ensure proper routing and processing +of the CloudEvent. Additional metadata for other purposes, that is related to +the event itself and not needed in the transportation or processing of the +CloudEvent, should instead be placed within the proper extensibility points of +the event (`data`) itself. + +Extension attributes should be kept minimal to ensure the CloudEvent can be +properly serialized and transported. For example, the Event producers should +consider the technical limitations that might be encountered when adding +extensions to a CloudEvent. For example, the +[HTTP Binary Mode](http-protocol-binding.md#31-binary-content-mode) uses HTTP +headers to transport metadata; most HTTP servers will reject requests with +excessive HTTP header data, with limits as low as 8kb. Therefore, the aggregate +size and number of extension attributes should be kept minimal. + +If an extension becomes popular then the specification authors might consider +moving it into the specification as a core attribute. This means that the +extension mechanism/process can be used as a way to vet new attributes prior to +formally adding them to the specification. + +### JSON Extensions + +As mentioned in the [Attributes](json-format.md#2-attributes) section of the +[JSON Event Format for CloudEvents](json-format.md) specification, CloudEvent +extension attributes are serialized as siblings to the specification defined +attributes - meaning, at the top-level of the JSON object. The authors of the +specification spent a long time considering all options and decided that this +was the best choice. Some of the rationale follows. + +Since the specifications follow [semver](https://semver.org/), this means that +new properties can be defined by future versions of the core specification +without requiring a major version number change - as long as these properties +are optional. In those cases, consider what an existing consumer would do with a +new (unknown) top-level property. While it would be free to ignore it, since it +is optional, in most cases it is believed that these properties would still want +to be exposed to the application receiving those events. This would allow those +applications to support these properties even if the infrastructure doesn't. +This means that unknown top-level properties (regardless of who defined them - +future versions of the spec or the event producer) are probably not going to be +ignored. So, while some other specifications define a specific property under +which extensions are placed (e.g. a top-level `extensions` property), the +authors decided that having two different locations within an incoming event for +unknown properties could lead to interoperability issues and confusion for +developers. + +Often extensions are used to test new potential properties of specifications +prior to them being formally adopted. If there were an `extensions` type of +property, in which this new property was serialized, then if that property were +to ever be adopted by the core specification it would be promoted (from a +serialization perspective) from the `extensions` property to be a top-level +property. If we assume that this new property will be optional, then as it is +adopted by the core specification it will be just a minor version increment, and +all existing consumers should still continue to work. However, consumers will +not know where this property will appear - in the `extensions` property or as a +top-level property. This means they might need to look in both places. What if +the property appears in both place but with different values? Will producers +need to place it in both places since they could have old and new consumers? +While it might be possible to define clear rules for how to solve each of the +potential problems that arise, the authors decided that it would be better to +simply avoid all of them in the first place by only having one location in the +serialization for unknown, or even new, properties. It was also noted that the +HTTP specification is now following a similar pattern by no longer suggesting +that extension HTTP headers be prefixed with `X-`. + +## Creating CloudEvents + +The CloudEvents specification purposely avoids being too prescriptive about how +CloudEvents are created. For example, it does not assume that the original event +source is the same entity that is constructing the associated CloudEvent for +that occurrence. This allows for a wide variety of implementation choices. +However, it can be useful for implementors of the specification to understand +the expectations that the specification authors had in mind as this might help +ensure interoperability and consistency. + +As mentioned above, whether the entity that generated the initial event is the +same entity that creates the corresponding CloudEvent is an implementation +choice. However, when the entity that is constructing/populating the CloudEvents +attributes is acting on behalf of the event source, the values of those +attributes are meant to describe the event or the event source and not the +entity calculating the CloudEvent attribute values. In other words, when the +split between the event source and the CloudEvents producer are not materially +significant to the event consumers, the spec defined attributes would typically +not include any values to indicate this split of responsibilities. + +This isn't to suggest that the CloudEvents producer couldn't add some additional +attributes to the CloudEvent, but those are outside the scope of the +interoperability defined attributes of the spec. This is similar to how an HTTP +proxy would typically minimize changes to the well-defined HTTP headers of an +incoming message, but it might add some additional headers that include +proxy-specific metadata. + +It is also worth noting that this separation between original event source and +CloudEvents producer could be small or large. Meaning, even if the CloudEvent +producer were not part of the original event source's ecosystem, if it is acting +on behalf of the event source, and its presence in the flow of the event is not +meaningful to event consumers, then the above guidance would still apply. + +When an entity is acting as both a receiver and sender of CloudEvents for the +purposes of forwarding, or transforming, the incoming event, the degree to which +the outbound CloudEvent matches the inbound CloudEvent will vary based on the +processing semantics of this entity. In cases where it is acting as proxy, where +it is simply forwarding CloudEvents to another event consumer, then the outbound +CloudEvent will typically look identical to the inbound CloudEvent with respect +to the spec defined attributes - see previous paragraph concerning adding +additional attributes. + +However, if this entity is performing some type of semantic processing of the +CloudEvent, typically resulting in a change to the value of the `data` +attribute, then it may need to be considered a distinct "event source" from the +original event source. And as such, it is expected that CloudEvents attributes +related to the event producer (such as `source` and `id`) would be changed from +the incoming CloudEvent. + +## Qualifying Protocols and Encodings + +The explicit goal of the CloudEvents effort, as expressed in the specification, +is "describing event data in a common way" and "to define interoperability of +event systems that allow services to produce or consume events, where the +producer and consumer can be developed and deployed independently". + +The foundations for such interoperability are open data formats and open +protocols, with CloudEvents aiming to provide such an open data format and +projections of its data format onto commonly used protocols and with commonly +used encodings. + +While each software or service product and project can obviously make its own +choices about which form of communication it prefers, its unquestionable that a +proprietary protocol that is private to such a product or project does not +further the goal of broad interoperability across producers and consumers of +events. + +Especially in the area of messaging and eventing, the industry has made +significant progress in the last decade in developing a robust and broadly +supported protocol foundation, like HTTP 1.1 and HTTP/2 as well as WebSockets or +events on the web, or MQTT and AMQP for connection-oriented messaging and +telemetry transfers. + +Some widely used protocols have become de-facto standards emerging out of strong +ecosystems of top-level consortia of three or more companies, and some out of +the strong ecosystems of projects released by a single company, and in either +case largely in parallel to the evolution of the previously mentioned standards +stacks. + +The CloudEvents effort shall not become a vehicle to even implicitly endorse or +promote project- or product-proprietary protocols, because that would be +counterproductive towards CloudEvents' original goals. + +For a protocol or encoding to qualify for a core CloudEvents event format or +protocol binding, it must belong to either one of the following categories: + +- The protocol has a formal status as a standard with a widely-recognized + multi-vendor protocol standardization body (e.g. W3C, IETF, OASIS, ISO) +- The protocol has a "de-facto standard" status for its ecosystem category, + which means it is used so widely that it is considered a standard for a given + application. Practically, we would like to see at least one open source + implementation under the umbrella of a vendor-neutral open-source organization + (e.g. Apache, Eclipse, CNCF, .NET Foundation) and at least a dozen independent + vendors using it in their products/services. + +Aside from formal status, a key criterion for whether a protocol or encoding +shall qualify for a core CloudEvents event format or protocol binding is +whether the group agrees that the specification will be of sustained practical +benefit for any party that is unrelated to the product or project from which the +protocol or encoding emerged. A base requirement for this is that the protocol +or encoding is defined in a fashion that allows alternate implementations +independent of the product or project's code. + +All other protocol and encoding formats for CloudEvents are welcome to be +included in a list pointing to the CloudEvents binding information in the +respective project's own public repository or site. + +## Proprietary Protocols and Encodings + +To encourage adoption of CloudEvents, this repository will collect CloudEvent +specs for proprietary protocols and encodings without endorsement. Repository +maintainers are not responsible for creating, maintaining, or notifying +maintainers of proprietary specs of drift from the CloudEvents spec. + +Proprietary specs will be hosted in their own repository or documentation site, +and collected in the [proprietary-specs](proprietary-specs.md) file. Proprietary +specs should follow the same format as the other specs for core protocols and +encodings. + +Proprietary specs will receive less scrutiny than a core spec, and as the +CloudEvents spec evolves, it is the responsibility of the maintainers of the +respective protocols and encodings to keep specs in sync with the CloudEvents +spec. If a proprietary spec falls too far out of date, CloudEvents may mark the +link to that spec as deprecated or remove it. + +In the case that multiple, incompatible specs are created for the same protocol, +the repository maintainers will be agnostic about which spec is correct and list +links to all specs. + +## Prior Art + +This section describes some of the input material used by the group during the +development of the CloudEvent specification. + +### Roles + +The list below enumerates the various participants, and scenarios, that might be +involved in the producing, managing or consuming of events. + +In these the roles of event producer and event consumer are kept distinct. A +single application context can always take on multiple roles concurrently, +including being both a producer and a consumer of events. + +1. Applications produce events for consumption by other parties, for instance + for providing consumers with insights about end-user activities, state + changes or environment observations, or for allowing complementing the + application's capabilities with event-driven extensions. + + Events are typically produced related to a context or a producer-chosen + classification. For example, a temperature sensor in a room might be + context-qualified by mount position, room, floor, and building. A sports + result might be classified by league and team. + + The producer application could run anywhere, such as on a server or a device. + + The produced events might be rendered and emitted directly by the producer or + by an intermediary; as example for the latter, consider event data + transmitted by a device over payload-size-constrained networks such as + LoRaWAN or ModBus, and where events compliant to this specification will be + rendered by a network gateway on behalf of the producer. + + For example, a weather station transmits a 12-byte, proprietary event payload + indicating weather conditions once every 5 minutes over LoRaWAN. A LoRaWAN + gateway is then used to publish the event to an Internet destination in the + CloudEvents format. The LoRaWAN gateway is the event producer, publishing on + behalf of the weather station, and will set event metadata appropriately to + reflect the source of the event. + +2. Applications consume events for the purposes such as display, archival, + analytics, workflow processing, monitoring the condition and/or providing + transparency into the operation of a business solution and its foundational + building blocks. + + The consumer application could run anywhere, such as on a server or a device. + + A consuming application will typically be interested in: + + - distinguishing events such that the exact same event is not processed + twice. + - identifying and selecting the origin context or the producer-assigned + classification. + - identifying the temporal order of the events relative to the originating + context and/or relative to a wall-clock. + - understanding the context-related detail information carried in the event. + - correlating event instances from multiple event producers and send them to + the same consumer context. + + In some cases, the consuming application might be interested in: + + - obtaining further details about the event's subject from the originating + context, like obtaining detail information about a changed object that + requires privileged access authorization. For example, a HR solution might + only publish very limited information in events for privacy reasons, and + any event consumer needing more data will have to obtain details related to + the event from the HR system under their own authorization context. + - interact with the event's subject at the originating context, for instance + reading a storage blob after having been informed that this blob has just + been created. + + Consumer interests motivate requirements for which information producers + ought to include an event. + +3. Middleware routes events from producers to consumers, or onwards to other + middleware. Applications producing events might delegate certain tasks + arising from their consumers' requirements to middleware: + + - Management of many concurrent interested consumers for one of multiple + classes or originating contexts of events + - Processing of filter conditions over a class or originating context of + events on behalf of consumers. + - Transcoding, like encoding in MsgPack after decoding from JSON + - Transformation that changes the event's structure, like mapping from a + proprietary format to CloudEvents, while preserving the identity and + semantic integrity of the event. + - Instant "push-style" delivery to interested consumers. + - Storing events for eventual delivery, either for pick-up initiated by the + consumer ("pull") or initiated by the middleware ("push") after a delay. + - Observing event content or event flow for monitoring or diagnostics + purposes. + + To satisfy these needs, middleware will be interested in: + + - A metadata discriminator usable for classification or contextualization of + events so that consumers can express interest in one or multiple such + classes or contexts. For instance, a consumer might be interested in all + events related to a specific directory inside a file storage account. + - A metadata discriminator that allows distinguishing the subject of a + particular event of that class or context. For instance, a consumer might + want to filter out all events related to new files ending with ".jpg" (the + file name being the "new file" event's subject) for the context describing + specific directory inside a file storage account that it has registered + interest on. + - An indicator for the encoding of the event and its data. + - An indicator for the structural layout (schema) for the event and its data. + + Whether its events are available for consumption via a middleware is a + delegation choice of the producer. + + In practice, middleware can take on the role of a + [Producer](spec.md#producer) when it changes the semantic meaning of an + event, a [Consumer](spec.md#consumer) when it takes action based on an event, + or [Intermediary](spec.md#intermediary) when it routes events without making + semantic changes. + +4. Frameworks and other abstractions make interactions with event platform + infrastructure simpler, and often provide common API surface areas for + multiple event platform infrastructures. + + Frameworks are often used for turning events into an object graph, and to + dispatch the event to some specific handling user-code or user-rule that + permits the consuming application to react to a particular kind of occurrence + in the originating context and on a particular subject. + + Frameworks are most interested in semantic metadata commonality across the + platforms they abstract, so that similar activities can be handled uniformly. + + For a sports application, a developer using the framework might be interested + in all events from today's game (subject) of a team in a league (topic of + interest) but wanting to handle reports of "goal" differently than reports of + "substitution". For this, the framework will need a suitable metadata + discriminator that frees it from having to understand the event details. + +### Value Proposition + +This section describes some of the use-cases that explain the value of +CloudEvents. + +#### Normalizing Events Across Services & Platforms + +Major event publishers (e.g. AWS, Microsoft, Google, etc.) all publish events in +different formats on their respective platforms. There are even a few cases +where services on the same provider publish events in different formats (e.g. +AWS). This forces event consumers to implement custom logic to read or munge +event data across platforms and occasionally across services on a single +platform. + +CloudEvents can offer a single experience for authoring consumers that handle +events across all platforms and services. + +#### Facilitating Integrations Across Services & Platforms + +Event data being transported across environments is increasingly common. +However, without a common way of describing events, delivery of events across +environments is hindered. There is no single way of determining where an event +came from and where it might be going. This prevents tooling to facilitate +successful event delivery and consumers from knowing what to do with event data. + +CloudEvents offers useful metadata which middleware and consumers can rely upon +to facilitate event routing, logging, delivery and receipt. + +#### Increasing Portability of Functions-as-a-Service + +Functions-as-a-Service (also known as serverless computing) is one of the +fastest growing trends in IT and it is largely event-driven. However, a primary +concern of FaaS is vendor lock-in. This lock-in is partially caused by +differences in function APIs and signatures across providers, but the lock-in is +also caused by differences in the format of event data received within +functions. - 生产的事件通常与上下文或生产者选择的分类相关。 - 例如，房间中的温度传感器可能被安装位置、房间、楼层和建筑物等上下文限定。 - 运动结果可以按联赛和球队分类。 +CloudEvents' common way of describing event data increases the portability of +Functions-as-a-Service. - 生产者应用程序可以在任何地方运行，例如在服务器或设备上。 +#### Improving Development & Testing of Event-Driven/Serverless Architectures + +The lack of a common event format complicates development and testing of +event-driven and serverless architectures. There is no easy way to mock events +accurately for development and testing purposes, and help emulate event-driven +workflows in a development environment. + +CloudEvents can enable better developer tools for building, testing and handling +the end-to-end lifecycle of event-driven and serverless architectures. - 生产的事件可能由生产者或中间人直接提供和发出； - 作为后者的示例，请考虑设备通过负载大小受限的网络（如 LoRaWAN 或 ModBus）传输的事件数据， - 并且符合此规范的事件将由网络网关代表生产者提供。 +#### Event Data Evolution - 例如，气象站每 5 分钟通过 LoRaWAN 传输一次 12 字节的专有事件payload用于指示天气状况。 - 然后使用 LoRaWAN 网关以 CloudEvents 格式将事件发布到 Internet 目标。 - LoRaWAN 网关是事件生产者，代表气象站发布事件，并将设置一定的元数据以反映事件的来源(气象站)。 +Most platforms and services version the data model of their events differently +(if they do this at all). This creates an inconsistent experience for publishing +and consuming the data model of events as those data models evolve. -2. 应用程序可能以以下目的： - 如显示、存档、分析、工作流处理、监控状态或提供业务解决方案及其基本构建模块的透明化 - 来消费事件。 +CloudEvents can offer a common way to version and evolve event data. This will +help event publishers safely version their data models based on best practices, +and this help event consumers safely work with event data as it evolves. - 消费者应用程序可以在任何地方运行，例如在服务器或设备上。 +#### Normalizing Webhooks - 消费应用程序通常对以下内容感兴趣： +Webhooks is a style of event publishing which does not use a common format. +Consumers of webhooks don’t have a consistent way to develop, test, identify, +validate, and overall process event data delivered via webhooks. - - 区分事件，使得完全相同的事件不会被处理两次。 - - 识别和选择源上下文或生产者指定的分类。 - - 确定事件相对于原始上下文或相对于时钟的时间顺序。 - - 了解事件中携带的上下文相关的详细信息。 - - 关联来自多个事件生产者的事件实例并将它们发送到相同的消费者上下文。 +CloudEvents can offer consistency in webhook publishing and consumption. - 在某些情况下，消费应用程序可能对以下内容感兴趣： +#### Policy Enforcement - - 从原始上下文中获取有关事件主题的更多详细信息，例如获取有关需要特权访问授权的已更改对象的详细信息。 - 例如，出于隐私原因，HR 解决方案可能仅在事件中发布非常有限的信息， - 任何需要更多数据的事件消费者都必须在其自己的授权上下文背景下从 HR 系统获取与事件相关的详细信息 - - 在原始上下文中与事件的主题进行交互，例如在被告知该数据块刚刚创建后读取存储该数据块。 +The transiting of events between systems may need to be filtered, transformed, +or blocked due to security and policy concerns. Examples may be to prevent +ingress or egress of the events such as event data containing sensitive +information or wanting to disallow the information flow between the sender and +receiver. - 消费者的兴趣激发了信息生产者应该包括事件的需求。 +A common event format would allow easier reasoning about the data being +transited and allow for better introspection of the data. -3. 中间件将事件从生产者路由到消费者，或转发到其他中间件。 - 产生事件的应用程序可能会将根据消费者需求产生的某些任务委托给中间件： +#### Event Tracing - - 管理同时对大量类别和上下文背景中的某个事件感兴趣的消费者。 - - 代表消费者在类或事件的原始上下文上处理过滤条件。 - - 转码，比如从 JSON 解码后在 MsgPack 中编码。 - - 更改事件结构的转换，例如从专有格式映射到 CloudEvents，同时保留事件的身份和语义完整性。 - - 即时“推送式”传输给感兴趣的消费者。 - - 存储最终传输的事件，用于由消费者发起的“拉”请求，或延迟后由中间件发起“推”请求。 - - 观察事件内容或事件流以进行监控或诊断。 - - 为了满足这些需求，中间件将对以下方面感兴趣： - - - 一种元数据鉴别器，可用于事件的分类或上下文化，以便消费者可以表达对一个或多个类或上下文的兴趣。 - 例如，消费者可能对文件存储帐户内的特定目录相关的所有事件感兴趣。 - - 一种元数据鉴别器，允许区分该类或上下文的特定事件的主题。例如，消费者可能希望过滤掉与以“.jpg”结尾的 - 新文件相关的所有事件（文件名是“新文件”事件的主题），以此表示它对感兴趣的文件存储账户下某个目录的 - 上下文环境。 - - 一个事件及其数据编码的指示器。 - - 一个事件及其数据的结构布局（模式）的指示器。 - - 事件是否可通过中间件消费取决于生产者的选择。 - - 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec.md#生产者)的角色， - 当它根据事件采取行动时可以扮演[消费者](spec.md#消费者)的角色， - 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec.md#中间人)的角色。 - -4. 框架和其他抽象使与事件平台基础设施间的交互更简单， - 并且通常为多个事件平台基础设施提供公共 API 区域。 - - 框架通常用于将事件转换为对象图，并将事件分派给某些特定的处理逻辑或用户规则， - 这些用户逻辑或用户规则允许消费应用程序对原始上下文和特定主题中的特定类型的事件做出反应。 - - 框架最感兴趣的是跨抽象平台的语义元数据通用性，以便可以统一处理类似的活动。 - - 对于体育应用程序，使用该框架的开发人员可能对联盟中一支球队今天的比赛（主题） - 的所有事件感兴趣，但希望以不同于“换人”事件的方式处理“得分”事件。 - 为此，框架将需要一个合适的元数据鉴别器，使其不必了解事件细节。 - -### 价值主张 - -本节介绍了一些能够展示 CloudEvents 价值主张的用例。 - -#### 跨服务和平台规范化事件 - -主要事件发布者（例如 AWS、Microsoft、Google 等）都在各自的平台上以不同的格式发布事件。 -甚至在少数情况下，同一提供商的服务以不同格式（例如 AWS）发布事件。 -这迫使事件消费者实现自定义逻辑以跨平台读取或处理事件数据，有时甚至需要跨单个平台的多个服务处理。 - -CloudEvents 可以为那些跨平台和服务处理事件的使用者提供单一体验。 - -#### 促进跨服务和平台的集成 - -跨环境传输的事件数据越来越普遍。 -然而，如果没有描述事件的通用方式，跨环境的事件传递就会受到阻碍。 -CloudEvents之前没有单一的方法可以确定事件的来源和可能的去向。 -这对研究成功传输事件事件工具和消费者知道如何处理事件数据形成了巨大阻碍。 - -CloudEvents 提供有用的元数据，中间件和消费者可以依赖这些元数据来促进事件路由、日志记录、传输和接收。 - -#### 提高功能即服务的可移植性 - -功能即服务（也称为serverless计算）是 IT 中增长最快的趋势之一，它主要是由事件驱动的。 -然而，FaaS 的一个主要问题是供应商锁定。 -这种锁定部分是由函数 API 和供应商之间签名的差异引起的， -锁定同样也是由函数内接收的事件数据格式的差异引起的。 - -CloudEvents提供描述事件数据的通用方式提高了功能即服务的可移植性。 - -#### 改进事件驱动/serverless架构的开发和测试 - -缺乏通用事件格式使事件驱动和serverless架构的开发和测试变得复杂。 -没有简单的方法可以准确地为开发和测试目的模拟事件，并帮助在开发环境中模拟事件驱动的工作流。 - -CloudEvents 可以提供更好的开发工具来构建、测试和处理事件驱动和无服务器架构的端到端生命周期。 - -#### 事件数据发展 - -大多数平台和服务对其事件的数据模型进行不同的版本控制（如果他们这样做的话）。 -随着这些数据模型的发展，这会为发布和使用事件的数据模型带来不一致的体验。 - -CloudEvents 可以提供一种通用的方式来版本化和演化事件数据的发展。 -这将帮助事件发布者根据最佳实践安全地对其数据模型进行版本控制， -并且这有助于事件消费者随着事件数据的发展安全地使用它。 - -#### 规范化 Webhook - -Webhooks 是一种不使用通用格式的来发布事件的模式。 -Webhook 的使用者没有一致的方式来开发、测试、识别、验证和整体处理通过 Webhook 传输的事件数据。 - -CloudEvents 可以提供 Webhook 发布和消费事件的一致性。 - -#### 安全策略 - -出于安全和策略考虑，可能需要过滤、转换或阻止系统之间的事件传输。 -比如可能需要防止事件的进入或退出，如包含敏感信息的事件数据或想要禁止发送方和接收方之间的信息流。 - -通用事件格式将允许更容易地推理正在传输的数据，并提供更好的数据自查。 - -#### 事件追踪 - -从源发送的事件可能会出现在一系列附加事件序列之中， -这些附加事件序列从各种中间件设备（例如事件代理和网关）发出。 -CloudEvents 在事件中包含元数据以将这些事件关联为事件序列的一部分，以便进行事件跟踪和故障排除。 +An event sent from a source may result in a sequence of additional events sent +from various middleware devices such as event brokers and gateways. CloudEvents +includes metadata in events to associate these events as being part of an event +sequence for the purpose of event tracing and troubleshooting. #### IoT -物联网设备会发送和接收与其功能相关的事件。 -例如，连接的恒温器将发送有关当前温度的遥测数据， -并可以接收改变温度的事件。 -这些设备通常具有受限的操作环境（cpu、内存），需要明确定义的事件消息格式。 -在很多情况下，这些消息是二进制编码的，而不是文本的。 -无论是直接来自设备还是通过网关转换，CloudEvents 都可以更好地描述消息的来源和消息中包含的数据格式。 - -#### 事件关联 - -一个serverless应用或工作流可能与来自不同事件源或事件生产者的多个事件相关联。 -例如，盗窃检测应用程序/工作流可能涉及运动事件和门/窗打开事件。 -一个serverless平台可能接收每种类型事件的许多实例，例如 它可以接收来自不同房屋的运动事件和开窗事件。 - -serverless平台需要将一种类型的事件实例与其他类型的事件实例正确关联， -并将接收到的事件实例映射到正确的应用/工作流实例。 -CloudEvents 将为任何事件使用者（例如serverless平台）提供一种标准方式， -以在事件数据中定位事件关联信息/令牌并将接收到的事件实例映射到正确的应用/工作流实例。 - -### 现有的数据格式 - -与上一节一样，对当前现状的调查（和理解）对CloudEvents 小组来说非常重要。 -为此，下面列出了在实践中被广泛使用的当前事件格式的样本。 +IoT devices send and receive events related to their functionality. For example, +a connected thermostat will send telemetry on the current temperature and could +receive events to change temperatures. These devices typically have a +constrained operating environment (cpu, memory) requiring a well-defined event +message format. In a lot of cases these messages are binary encoded instead of +textual. Whether directly from the device or transformed via a gateway, +CloudEvents would allow for a better description of the origin of the message +and the format of the data contained within the message. + +#### Event Correlation + +A serverless application/workflow could be associated with multiple events from +different event sources/producers. For example, a burglary detection +application/workflow could involve both a motion event and a door/window open +event. A serverless platform could receive many instances of each type of +events, e.g. it could receive motion events and window open events from +different houses. + +The serverless platform needs to correlate one type of event instance correctly +with other types of event instances and map a received event instance to the +correct application/workflow instance. CloudEvents will provide a standard way +for any event consumer (e.g. the serverless platform) to locate the event +correlation information/token in the event data and map a received event +instance to the correct application/workflow instance. + +### Existing Event Formats + +As with the previous section, the examination (and understanding) of the current +state of the world was very important to the group. To that end, a sampling of +existing current event formats that are used in practice today was gathered. #### Microsoft - Event Grid @@ -588,7 +780,8 @@ CloudEvents 将为任何事件使用者（例如serverless平台）提供一种 #### AWS - CloudWatch Events -AWS 上的很大一部分事件处理系统都在使用这种格式。 +A high proportion of event-processing systems on AWS are converging on the use +of this format. ``` { From 4cc626f9f2cce96f304520d1f852efc909086e19 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:28:25 +0800 Subject: [PATCH 50/60] Create spec_CN.md Signed-off-by: JieDing --- spec_CN.md | 478 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 478 insertions(+) create mode 100644 spec_CN.md diff --git a/spec_CN.md b/spec_CN.md new file mode 100644 index 000000000..7c9c1a8cd --- /dev/null +++ b/spec_CN.md @@ -0,0 +1,478 @@ +# CloudEvents 核心规范- 1.0 版本 + +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. + +## 摘要 + +CloudEvents 是一个用于定义事件格式的供应商中立规范。 + +## 目录 + +- [概览](#概览) +- [符号和术语](#符号和术语) +- [上下文属性](#上下文属性) +- [事件数据](#事件数据) +- [大小限制](#大小限制) +- [隐私与安全](#隐私与安全) +- [示例](#示例) + +## 概览 + +事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 + +对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。 +它同样限制了那些用来帮助事件数据完成 跨环境传输的库(如SDKs)， +工具(如事件路由器)和基础设施(如事件追踪系统)的发展。 +总体来看，这种匮乏严重阻碍了事件数据的可移植性和生产力。 + +CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 + +事件格式指定如何使用某些编码格式序列化一个 CloudEvent。 +支持那些编码且兼容 CloudEvents 的实现必须遵守相应事件格式中指定的编码规则。 +所有实现都必须支持 [JSON 格式](json-format.md)。 + +有关规范背后的历史、开发和设计原理等更多信息， +请参阅 CloudEvents [入门文档](primer.md)。 + +## 符号和术语 + +### 符号约定 + +本文档中的关键词 +"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 需要按照 +[RFC 2119](https://tools.ietf.org/html/rfc2119) 中的描述来理解。 + +为清楚起见， +当一个功能被标记为“OPTIONAL”时，这意味着消息的 +[生产者](#生产者)和[消费者](#消费者) 都可以自行选择是否支持该功能。 +换句话说，生产者可以在需要时在消息中包含该功能，消费者也可以在需要时选择支持该功能。 +不支持该功能的消费者将默默地忽略该部分消息。 +生产者需要做好消费者并没有启用该功能的准备。 +[中间人](#中间人) 应当转发OPTIONAL属性。 + +### 术语 + +本规范定义了下列术语 + +#### 发生 + +“发生”是指在软件系统运行期间对事实状态的捕获。 +这可能是由于系统发出了信号或系统观察到信号、状态更改、计时器超时 +或任何其他值得注意的活动而发生的。 +例如，设备可能会因为电池电量低或虚拟机即将执行计划的重启而进入警报状态。 + +#### 事件 + +“事件”是表示一条"发生"及其上下文的数据记录。 +事件从事件生产者（源）路由到对它感兴趣的事件消费者。 +事件中包含的信息帮助完成路由操作，但事件不会标识特定的路由目的地。 +事件将包含两种类型的信息：表示"发生"的 [事件数据](#事件数据) +和提供有关事件的环境信息的[上下文](#上下文) 元数据。 +一次"发生"可能导致多个事件的产生。 + +#### 生产者 + +“生产者”是一种特定的实例、进程或设备，它能够创建用来描述CloudEvent的数据结构。 + +#### 源 + +"源"是事件发生的上下文环境。在分布式系统中，它可能由多个生产者组成。 +如果一个源无法查看到CloudEvents，那么一定有有外部的生产者在代替源来生产CloudEvent。 + +#### 消费者 + +一个“消费者”会接收事件并根据事件采取一定的行为。 +它使用上下文环境和事件数据来执行一些逻辑，这可能会导致新事件的发生。 + +#### 中间人 + +一个“中间人”会接收包含事件的消息， +并将其转发给下一个接收者，但该接收者可能是另一个中间人或事件[消费者](#消费者)。 +中间人的典型任务就是根据[上下文](#上下文)环境中的信息将事件路由到接收者。 + +#### 上下文 + +上下文环境元数据被封装在[上下文-属性](#上下文-属性)中。 +工具和应用程序代码可以使用此信息来识别事件与系统方面或事件与其他事件的关系。 + +#### 数据 + +关于事件的特定域信息（即有效负载）。这可能包括有关事件的信息、有关已更改数据的详细信息等。 +有关更多信息，请参阅[事件数据](#事件数据)部分。 + +#### 事件格式 + +一个事件格式会指定如何将 CloudEvent 序列化为字节序列。 +独立事件格式（例如 [JSON 格式](json-format.md)）指定独立于任何协议或存储介质的序列化。 +协议绑定可以定义依赖于协议的格式。 + +#### 消息 + +事件通过消息从源传输到目标。 + +“结构化模式消息”是一种使用独立事件格式对事件进行完全编码并存储在消息体中的消息。 + +“二进制模式消息”会将事件数据存储在消息体中，并将事件属性作为消息元数据的一部分存储下来。 + +#### 协议 + +消息可以通过各种行业标准协议 +（例如 HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或平台/供应商 +专有协议（AWS Kinesis、Azure 事件网格）传输。 + +#### 协议绑定 + +协议绑定描述了如何通过给定协议发送和接收事件，特别是如何将事件映射到该协议的消息中去。 + +## 上下文属性 + +每个符合本规范的 CloudEvent 必须包括指定为 REQUIRED 的上下文属性， +可以包括一个或多个OPTIONAL上下文属性， +并且可以包括一个或多个扩展属性。 + +这些属性虽然描述了事件，但被设计为可以独立于事件数据进行序列化。 +这允许在不反序列化事件数据的情况下，在目的检查这些上下文属性。 + +### 属性命名约定 + +CloudEvents 规范定义了到各种协议和编码的映射，随附的 CloudEvents SDK 面向各种运行时和编程语言。 +其中一些将元数据元素区分大小写，而另一些则不区分， +并且单个 CloudEvent 可能通过涉及到协议、编码和运行时混合的多个跃点进行路由。 +因此，本规范限制了所有属性的可用字符集，以防止区分大小写问题或与通用语言中标识符的合法字符集冲突问题。 + +CloudEvents 属性名称必须由来自 ASCII 字符集的小写字母（“a”到“z”）或数字（“0”到“9”）组成。 +属性名称应该是描述性的和简洁的，并且长度不应超过 20 个字符。 + +### 类型系统 + +以下抽象数据类型可用于属性。 +这些类型中的每一种都可以由不同的事件格式和协议元数据字段以不同的方式表示。 +本规范为所有实现必须支持的每种类型定义了规范的字符串编码。 + +- `Boolean` - “true”或“false”的布尔值。 + - 字符串编码：区分大小写的`true` 或 `false`值。 +- `Integer` -范围在 -2,147,483,648 到 +2,147,483,647 （包含）之间的整数。 + 这是有符号 32 位二进制补码编码的范围。 + 事件格式不必使用此编码，但它们必须使用在此范围内的`Integer` 值。 + - 字符串编码: 符合 + [RFC 7159, 第 6 节](https://tools.ietf.org/html/rfc7159#section-6) + JSON 数字的整数部分 +- `String` - 允许的 Unicode 字符序列。 不允许使用以下字符： + - 范围 U+0000-U+001F 和 U+007F-U+009F（包含首尾）中的“控制字符”， + 因为大多数没有商定的含义，还有一些，例如 U+000A（换行符）， 在如 HTTP 头部之类的上下文中不可用。 + -[被 Unicode 标识为非字符的](http://www.unicode.org/faq/private_use.html#noncharacters) + 代码点。 + - 被 Unicode 标识为代理项的代码点, 范围 U+D800-U+DBFF 和 U+DC00-U+DFFF（包含首尾） + , 除非被合理的用作代理对. 因此（在 JSON 符号中） + “\uDEAD”是无效的，因为它是一个未配对的代理，而“\uD800\uDEAD”是合法的。 +- `Binary` - 字节序列. + - 字符串编码: 基于 + [RFC4648](https://tools.ietf.org/html/rfc4648) 的Base64 编码。 +- `URI` - 绝对统一资源标识符。 + - 字符串编码: + [RFC 3986 第 4.3 节](https://tools.ietf.org/html/rfc3986#section-4.3) + 中定义的 `Absolute URI` 。 +- `URI-reference` - 统一资源标识符引用。 + - 字符串编码: + [RFC 3986 第 4.1 节](https://tools.ietf.org/html/rfc3986#section-4.1) + 中定义的`URI-reference` 。 +- `Timestamp` - 使用公历的日期和时间表达式。 + - 字符串编码: [RFC 3339](https://tools.ietf.org/html/rfc3339) 。 + +所有上下文属性值必须是上面列出的类型之一。 +属性值可以表示为原生类型或规范字符串。 + +当强类型编程语言表示 CloudEvent 或任何扩展时， +必须能够在规范字符串编码与对应抽象类型的运行时/编程语言类型之间进行转换。 + +例如，在给定的实现中，`time` 属性可能由编程语言的本地时间类型表示， +但它必须是可设置提供 RFC3339 字符串的， +并且当映射到 HTTP 消息头时，它必须可转换为 RFC3339 字符串。 + +CloudEvents 协议绑定或事件格式实现同样必须能够 +在规范字符串编码与协议元数据字段中的对应数据类型之间进行转换。 + +`Timestamp` 类型的属性值确实可能以字符串形式路由通过多个跃点， +并且仅在生产者和最终消费者处实现为本地运行时/语言类型。 +`Timestamp` 类型也可以作为本机协议类型路由， +并且可以在生产者和消费者端映射到/从各自的语言/运行时类型，但永远不会转为字符串格式。 + +序列化机制的选择将决定上下文属性和事件数据将如何序列化。 +例如，在 JSON 序列化的情况下，上下文属性和事件数据可能都出现在同一个 JSON 对象中。 + +### 必要属性 + +下列属性必须自所有的 CloudEvents 中展示： + +#### id + +- 类型: `String` +- 描述: 标识一个事件。 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 + 如果重复的事件被重新发送（例如由于网络错误），它可能具有相同的 `id`。 + Consumers MAY assume that + 消费者可以假设具有相同`source` 和 `id`的事件是重复的。 +- 示例: + - 一个由生产者维护的事件计数器 + - 一个 UUID +- 约束条件: + - 必要的 + - 必须是非空字符串 + - 在生产者的范围内必须是唯一的 + +#### source + +- 类型: `URI-reference` +- 描述: 标识事件发生的上下文背景。 这通常包括诸如事件源类型、发布事件的组织 + 或产生事件的过程等信息。URI 中编码的数据背后的确切语法和语义由事件生产者定义。 + + 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 + + 应用程序可以为每个不同的生产者分配一个唯一的`source`， + 这使得生成唯一 ID 变得容易，因为没有其他生产者将拥有相同的来源。 + 应用程序可以使用 UUIDs、URNs、DNS权威机构或特定于应用程序的方案来创建唯一的`source` 标识符。 + + 一个来源可以包括多个生产者。 + 在这种情况下，生产者必须协作以确保每个不同事件的 `source` + `id`都是唯一的。 + +- 约束条件: + - 必要的 + - 必须是非空 URI-reference + - 推荐使用 绝对 URI +- 示例 + - 具有 DNS 权限的 Internet 范围唯一 URI： + - https://github.com/cloudevents + - mailto:cncf-wg-serverless@lists.cncf.io + - 具有 UUID 的通用唯一 URN： + - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 + - 应用程序专有的标识符 + - /cloudevents/spec/pull/123 + - /sensors/tn-1234567/alerts + - 1-555-123-4567 + +#### specversion + +- 类型: `String` +- 描述: 事件使用的 CloudEvents 规范的版本。 + 这让解释上下文环境更容易。 + 当引用这个版本的规范时，兼容的事件生产者必须使用 `1.0` 的值。 +- 约束条件: + - 必要的 + - 必须是非空字符串 + +#### type + +- 类型: `String` +- 描述: 该属性包含一个值，描述与原始事件相关的事件类型。 + 该属性通常用于路由、可观察性、策略实施等。其格式是生产者定义的，可能包括诸如 `type`版本之类的信息 + -从 + [入门文档-属性版本控制](primer.md#属性版本控制) 中获得更多信息 + +- 约束条件: + - 必要的 + - 必须是非空字符串 + - 应该以反向 DNS 名称作为前缀。该前缀域表明了定义此事件类型语义的组织。 +- 示例 + - com.github.pull.create + - com.example.object.delete.v2 + +### 可选属性 + +下列属性在 CloudEvents 中是可选的. 在 +[符号约定](#notational-conventions) 中查看更多 OPTIONAL 定义的信息。 + +#### datacontenttype + +- 类型: `String` [RFC 2046](https://tools.ietf.org/html/rfc2046) +- 描述: `data`值的内容类型。 此属性使`data`能够承载任何类型的内容， + 因此格式和编码可能与所选事件格式的不同。 + 例如，使用 [JSON envelope](./json-format.md#3-envelope) + 格式呈现的事件可能在数据中携带 XML 的payload，这个属性可以用来通知消费者 + 设置"application/xml"。 + 关于`data`内容如何提供不同的`datacontenttype`的值的规则在事件格式规范中定义。 + 例如，JSON 事件格式定义了 [3.1 节](./json-format.md#31-handling-of-data)中的关系。 + 对于某些二进制模式协议绑定， + 此字段直接能映射到相应协议的内容类型的元数据属性上。 + 二进制模式和内容类型元数据映射的规范规则可以在各自的协议中找到。 + + 在某些事件格式中，可以省略 `datacontenttype` 属性。 + 例如，如果 JSON 格式的事件没有 `datacontenttype` 属性， + 则表示该`data`是符合“application/json”媒体类型的 JSON 值。 + 换句话说：一个没有 `datacontenttype` 的 JSON 格式的事件完全等同于 + 一个带有 `datacontenttype="application/json"`的事件。 + + 当将没有 `datacontenttype` 属性的事件消息转换为不同的格式或协议绑定时， + 目标 `datacontenttype` 应该显式设置为事件源的隐含或默认的 `datacontenttype`。 + +- 约束条件: + - 可选的 + - 若有则必须遵守 + [RFC 2046](https://tools.ietf.org/html/rfc2046) 制定的格式 +- 媒体类型示例 + [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml) + +#### dataschema + +- 类型: `URI` +- 描述: 标识 `data` 遵守的规范。 对模式的不兼容的更改应该由不同的 URI 体现。 在 + [入门文档-属性版本控制](primer.md#属性版本控制) + 中查看更多信息。 +- 约束条件: + - 可选的 + - 若有必须是非空的 URI + +#### subject + +- 类型: `String` +- 描述: 这个属性描述了事件生产者 (由`source`标识) 上下文环境中的主题信息。 + 在发布-订阅场景中，订阅者通常会订阅`source`发出的事件， + 但如果`source` 的上下文环境具有内部子结构， + 则单独的`source`标识符可能不足以作为任何指定事件的限定符。 + + 在上下文元数据中识别事件的主题（与仅在数据负载中相反） + 对于中间件无法解释`data` 内容的通用订阅过滤场景特别有用。 + 在上面的示例中，订阅者可能只对名称以“.jpg”或“.jpeg”结尾的blob感兴趣， + 此时`subject` 属性允许为该事件子集构建简单有效的字符串后缀过滤器。 + +- 约束条件: + - 可选的 + - 若有必须是非空字符串 +- 示例: + - 订阅者可能对在blob在blob存储容器中创建的时候感兴趣并订阅。 + 在这个场景下，事件`source`标示出订阅的范围（存储容器），`type` 标识出 + blob 创建" 这个事件，`id` 唯一标识出事件示例，以区分已创建同名blob的事件， + 而新创建的blob的名字可以放在`subject`属性中： + - `source`: https://example.com/storage/tenant/container + - `subject`: mynewfile.jpg + +#### time + +- 类型: `Timestamp` +- 描述: 事件发生的时间戳。 + 如果无法确定发生的时间，则 CloudEvents 生产者可以将此属性设置为其他时间（例如当前时间）。 + 但是在这方面，同一`source`的所有生产者必须保持一致。 + 换句话说，要么它们都使用发生的实际时间，要么它们都使用相同的算法来确定所使用的值。 + +- 约束条件: + - 可选的 + - 若有则必须遵守 + [RFC 3339](https://tools.ietf.org/html/rfc3339) + +### 扩展上下文属性 + +CloudEvent 可以包含任意数量的具有不同名称的附加上下文属性，被称为"扩展属性"。 +扩展属性必须遵循相同的[命名约定](#属性命名约定)并使用与标准属性相同的 +[类型系统](#类型系统)。 +扩展属性在本规范中没有定义好的含义， +它们允许外部系统将元数据附加到事件，就像 HTTP 自定义头部一样。 + +扩展属性总是如标准属性一样，根据绑定规则进行序列化。 +然而，该规范不阻止扩展将事件属性值复制到消息的其他部分， +以便与也其它处理消息的非 CloudEvents 系统进行交互。 +如果复制的值与云事件序列化值不同，执行此操作的扩展规范应该指定接收者如何解释消息。 + +#### 定义扩展 + +在 +[CloudEvent-属性扩展](primer.md#CloudEvent-属性扩展) +查阅有关扩展使用和定义等相关信息。 + +扩展的定义应该完全定义属性的方方面面——例如 它的名称、类型、语义含义和可能的值。 +新的扩展定义应该使用一个足够描述性的名称来减少与其他扩展的名称冲突的机会。 +特别是，扩展作者应该检查[扩展文件](documented-extensions.md)中 +已知的扩展集——不仅是可能的名称冲突，还有相同目的冲突的扩展。 + +许多协议为发送者提供了包含额外元数据的能力，例如作为 HTTP 头部。 +虽然没有强制要求 CloudEvents 接受者处理和传递它们， +但建议接受者通过某种机制进行处理，以明确它们是非 CloudEvents 的元数据。 + +下面是一个示例，说明了 CloudEvents 对附加属性的需求。 +在许多物联网和企业用例中，事件可用于跨多种类型事件执行操作的serverless应用程序中。 +为了支持这样的用例，事件生产者需要向“上下文属性”添加额外的身份属性， +事件消费者可以使用这些属性将这个事件与其他事件相关联。 +如果此类身份属性恰好是事件“数据”的一部分， +则事件生产者还会将身份属性添加到“上下文属性”中， +以便事件消费者可以轻松访问此信息，而无需解码和检查事件数据。 +此类身份属性还可用于帮助中间网关确定如何路由事件。 + +## 事件数据 + +正如[数据](#数据)所定义的那样，CloudEvents 可以包括有关事件的特定域的信息。 +这些信息将被封装在`data`中。 + +- 描述: 事件负载。 本规范对该信息的类型不作任何限制。 + 它被编码为一种媒体格式，这种格式由`datacontenttype` 属性(如 application/json)指定， + 并在存在这些相应属性时遵循`dataschema`格式。 + It is encoded into a media format + +- 约束条件: + - 可选的 + +# 大小限制 + +在很多情况下，CloudEvents 将通过一个或多个通用中间人进行转发， +每个中间人都可能对转发事件的大小施加限制。 +CloudEvents 也可能直接被路由到消费者，如嵌入式设备， +这些设备是受存储或内存限制的，对单个大型事件表现不佳。 + +事件的“大小”是它的线路大小，包括在线路上为事件传输的每一位： +协议帧元数据、事件元数据和事件数据，基于所选的事件格式和所选的协议绑定。 + +如果应用程序配置需要跨不同协议路由事件或重新编码事件， +应用程序能使用的效率最低的协议和编码，都修腰符合这些大小限制： + +- 中间人转发的事件大小必须为 64 KB 或更小。 +- 消费者应该能接受大小至少为 64 KB 的事件。 + +为了方便，上述规则将允许生产者安全地发布最大 64KB 的事件。 +这里的安全意味着生产者期望事件被所有中间人接受并合理地转发。 +它是在任何特定消费者的控制之下，无论消费者是否由于本地考虑而选择接受或拒绝该大小的事件。 + +通常，CloudEvents 发布者应该通过避免将大型数据项嵌入到事件而使用事件有效链接到此类数据项， +来保持事件紧凑。 +从访问控制的角度来看，这种方法对更广泛的事件分布式化有帮助， +因为通过解析链接访问与事件相关的细节能实现差异化访问控制和选择性披露， +而不是将敏感详细数据直接嵌入到事件中。 + +# 隐私与安全 + +互操作性是本规范背后的主要驱动力， +实现此目标需要一些信息明确可用，这可能导致信息的泄漏。 + +考虑以下事项以防止信息意外泄漏，尤其是在利用第三方平台和通信网络时： + +- 上下文属性 + + 敏感信息不应在上下文属性中携带。 + + CloudEvent 生产者、消费者和中间人可以自查并记录下上下文属性。 + +- 数据 + + 特定的[事件数据](#事件数据) 应该被加密以限制对受信任方的可见性。 + 用于这种加密的机制是生产者和消费者之间的协议，不在本规范的讨论范围内。 + +- 协议绑定 + 应该采用协议级别的安全性机制来确保 CloudEvents 完成可信和安全的交换。 + +# 示例 + +以下示例展示了一个序列化为 JSON 的 CloudEvent： + +```JSON +{ + "specversion" : "1.0", + "type" : "com.github.pull.create", + "source" : "https://github.com/cloudevents/spec/pull", + "subject" : "123", + "id" : "A234-1234-1234", + "time" : "2018-04-05T17:31:00Z", + "comexampleextension1" : "value", + "comexampleothervalue" : 5, + "datacontenttype" : "text/xml", + "data" : "" +} +``` From f4c90302423da2fcdcf5f260e5b182d091d858df Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:29:15 +0800 Subject: [PATCH 51/60] Update spec.md Signed-off-by: JieDing --- spec.md | 863 +++++++++++++++++++++++++++++++------------------------- 1 file changed, 472 insertions(+), 391 deletions(-) diff --git a/spec.md b/spec.md index 7c9c1a8cd..5d3899541 100644 --- a/spec.md +++ b/spec.md @@ -1,466 +1,547 @@ -# CloudEvents 核心规范- 1.0 版本 +# CloudEvents - Version 1.0 -Declaration： This manual aims to provide a fast and brief introduction of CloudEvents -in Chinese for people who are new to CloudEvents. -Most of the content is translated from the original English version. -It is strongly recommended to read the English version if you find anything lost in translation. +## Abstract -## 摘要 +CloudEvents is a vendor-neutral specification for defining the format of event +data. -CloudEvents 是一个用于定义事件格式的供应商中立规范。 +## Table of Contents -## 目录 +- [Overview](#overview) +- [Notations and Terminology](#notations-and-terminology) +- [Context Attributes](#context-attributes) +- [Event Data](#event-data) +- [Size Limits](#size-limits) +- [Privacy & Security](#privacy-and-security) +- [Example](#example) -- [概览](#概览) -- [符号和术语](#符号和术语) -- [上下文属性](#上下文属性) -- [事件数据](#事件数据) -- [大小限制](#大小限制) -- [隐私与安全](#隐私与安全) -- [示例](#示例) +## Overview -## 概览 +Events are everywhere. However, event producers tend to describe events +differently. -事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 +The lack of a common way of describing events means developers are constantly +re-learning how to consume events. This also limits the potential for libraries, +tooling and infrastructure to aid the delivery of event data across +environments, like SDKs, event routers or tracing systems. The portability and +productivity that can be achieved from event data is hindered overall. -对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。 -它同样限制了那些用来帮助事件数据完成 跨环境传输的库(如SDKs)， -工具(如事件路由器)和基础设施(如事件追踪系统)的发展。 -总体来看，这种匮乏严重阻碍了事件数据的可移植性和生产力。 +CloudEvents is a specification for describing event data in common formats to +provide interoperability across services, platforms and systems. -CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 +Event Formats specify how to serialize a CloudEvent with certain encoding +formats. Compliant CloudEvents implementations that support those encodings MUST +adhere to the encoding rules specified in the respective event format. All +implementations MUST support the [JSON format](json-format.md). -事件格式指定如何使用某些编码格式序列化一个 CloudEvent。 -支持那些编码且兼容 CloudEvents 的实现必须遵守相应事件格式中指定的编码规则。 -所有实现都必须支持 [JSON 格式](json-format.md)。 +For more information on the history, development and design rationale behind the +specification, see the [CloudEvents Primer](primer.md) document. -有关规范背后的历史、开发和设计原理等更多信息， -请参阅 CloudEvents [入门文档](primer.md)。 +## Notations and Terminology -## 符号和术语 +### Notational Conventions -### 符号约定 +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). -本文档中的关键词 -"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 需要按照 -[RFC 2119](https://tools.ietf.org/html/rfc2119) 中的描述来理解。 +For clarity, when a feature is marked as "OPTIONAL" this means that it is +OPTIONAL for both the [Producer](#producer) and [Consumer](#consumer) of a +message to support that feature. In other words, a producer can choose to +include that feature in a message if it wants, and a consumer can choose to +support that feature if it wants. A consumer that does not support that feature +will then silently ignore that part of the message. The producer needs to be +prepared for the situation where a consumer ignores that feature. An +[Intermediary](#intermediary) SHOULD forward OPTIONAL attributes. -为清楚起见， -当一个功能被标记为“OPTIONAL”时，这意味着消息的 -[生产者](#生产者)和[消费者](#消费者) 都可以自行选择是否支持该功能。 -换句话说，生产者可以在需要时在消息中包含该功能，消费者也可以在需要时选择支持该功能。 -不支持该功能的消费者将默默地忽略该部分消息。 -生产者需要做好消费者并没有启用该功能的准备。 -[中间人](#中间人) 应当转发OPTIONAL属性。 +### Terminology -### 术语 +This specification defines the following terms: -本规范定义了下列术语 +#### Occurrence -#### 发生 +An "occurrence" is the capture of a statement of fact during the operation of a +software system. This might occur because of a signal raised by the system or a +signal being observed by the system, because of a state change, because of a +timer elapsing, or any other noteworthy activity. For example, a device might go +into an alert state because the battery is low, or a virtual machine is about to +perform a scheduled reboot. -“发生”是指在软件系统运行期间对事实状态的捕获。 -这可能是由于系统发出了信号或系统观察到信号、状态更改、计时器超时 -或任何其他值得注意的活动而发生的。 -例如，设备可能会因为电池电量低或虚拟机即将执行计划的重启而进入警报状态。 +#### Event -#### 事件 +An "event" is a data record expressing an occurrence and its context. Events are +routed from an event producer (the source) to interested event consumers. The +routing can be performed based on information contained in the event, but an +event will not identify a specific routing destination. Events will contain two +types of information: the [Event Data](#event-data) representing the Occurrence +and [Context](#context) metadata providing contextual information about the +Occurrence. A single occurrence MAY result in more than one event. -“事件”是表示一条"发生"及其上下文的数据记录。 -事件从事件生产者（源）路由到对它感兴趣的事件消费者。 -事件中包含的信息帮助完成路由操作，但事件不会标识特定的路由目的地。 -事件将包含两种类型的信息：表示"发生"的 [事件数据](#事件数据) -和提供有关事件的环境信息的[上下文](#上下文) 元数据。 -一次"发生"可能导致多个事件的产生。 +#### Producer -#### 生产者 +The "producer" is a specific instance, process or device that creates the data +structure describing the CloudEvent. -“生产者”是一种特定的实例、进程或设备，它能够创建用来描述CloudEvent的数据结构。 +#### Source -#### 源 +The "source" is the context in which the occurrence happened. In a distributed +system it might consist of multiple [Producers](#producer). If a source is not +aware of CloudEvents, an external producer creates the CloudEvent on behalf of +the source. -"源"是事件发生的上下文环境。在分布式系统中，它可能由多个生产者组成。 -如果一个源无法查看到CloudEvents，那么一定有有外部的生产者在代替源来生产CloudEvent。 +#### Consumer -#### 消费者 +A "consumer" receives the event and acts upon it. It uses the context and data +to execute some logic, which might lead to the occurrence of new events. -一个“消费者”会接收事件并根据事件采取一定的行为。 -它使用上下文环境和事件数据来执行一些逻辑，这可能会导致新事件的发生。 +#### Intermediary -#### 中间人 +An "intermediary" receives a message containing an event for the purpose of +forwarding it to the next receiver, which might be another intermediary or a +[Consumer](#consumer). A typical task for an intermediary is to route the event +to receivers based on the information in the [Context](#context). -一个“中间人”会接收包含事件的消息， -并将其转发给下一个接收者，但该接收者可能是另一个中间人或事件[消费者](#消费者)。 -中间人的典型任务就是根据[上下文](#上下文)环境中的信息将事件路由到接收者。 +#### Context + +Context metadata will be encapsulated in the +[Context Attributes](#context-attributes). Tools and application code can use +this information to identify the relationship of Events to aspects of the system +or to other Events. + +#### Data + +Domain-specific information about the occurrence (i.e. the payload). This might +include information about the occurrence, details about the data that was +changed, or more. See the [Event Data](#event-data) section for more +information. -#### 上下文 +#### Event Format + +An Event Format specifies how to serialize a CloudEvent as a sequence of bytes. +Stand-alone event formats, such as the [JSON format](json-format.md), specify +serialization independent of any protocol or storage medium. Protocol Bindings +MAY define formats that are dependent on the protocol. + +#### Message + +Events are transported from a source to a destination via messages. + +A "structured-mode message" is one where the event is fully encoded using +a stand-alone event format and stored in the message body. + +A "binary-mode message" is one where the event data is stored in the message +body, and event attributes are stored as part of message meta-data. + +#### Protocol + +Messages can be delivered through various industry standard protocol (e.g. HTTP, +AMQP, MQTT, SMTP), open-source protocols (e.g. Kafka, NATS), or platform/vendor +specific protocols (AWS Kinesis, Azure Event Grid). + +#### Protocol Binding + +A protocol binding describes how events are sent and received over a given +protocol, in particular how events are mapped to messages in that protocol. + +## Context Attributes + +Every CloudEvent conforming to this specification MUST include context +attributes designated as REQUIRED, MAY include one or more OPTIONAL context +attributes and MAY include one or more extension attributes. + +These attributes, while descriptive of the event, are designed such that they +can be serialized independent of the event data. This allows for them to be +inspected at the destination without having to deserialize the event data. -上下文环境元数据被封装在[上下文-属性](#上下文-属性)中。 -工具和应用程序代码可以使用此信息来识别事件与系统方面或事件与其他事件的关系。 - -#### 数据 - -关于事件的特定域信息（即有效负载）。这可能包括有关事件的信息、有关已更改数据的详细信息等。 -有关更多信息，请参阅[事件数据](#事件数据)部分。 - -#### 事件格式 - -一个事件格式会指定如何将 CloudEvent 序列化为字节序列。 -独立事件格式（例如 [JSON 格式](json-format.md)）指定独立于任何协议或存储介质的序列化。 -协议绑定可以定义依赖于协议的格式。 - -#### 消息 - -事件通过消息从源传输到目标。 - -“结构化模式消息”是一种使用独立事件格式对事件进行完全编码并存储在消息体中的消息。 - -“二进制模式消息”会将事件数据存储在消息体中，并将事件属性作为消息元数据的一部分存储下来。 - -#### 协议 - -消息可以通过各种行业标准协议 -（例如 HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或平台/供应商 -专有协议（AWS Kinesis、Azure 事件网格）传输。 - -#### 协议绑定 - -协议绑定描述了如何通过给定协议发送和接收事件，特别是如何将事件映射到该协议的消息中去。 - -## 上下文属性 - -每个符合本规范的 CloudEvent 必须包括指定为 REQUIRED 的上下文属性， -可以包括一个或多个OPTIONAL上下文属性， -并且可以包括一个或多个扩展属性。 - -这些属性虽然描述了事件，但被设计为可以独立于事件数据进行序列化。 -这允许在不反序列化事件数据的情况下，在目的检查这些上下文属性。 - -### 属性命名约定 - -CloudEvents 规范定义了到各种协议和编码的映射，随附的 CloudEvents SDK 面向各种运行时和编程语言。 -其中一些将元数据元素区分大小写，而另一些则不区分， -并且单个 CloudEvent 可能通过涉及到协议、编码和运行时混合的多个跃点进行路由。 -因此，本规范限制了所有属性的可用字符集，以防止区分大小写问题或与通用语言中标识符的合法字符集冲突问题。 - -CloudEvents 属性名称必须由来自 ASCII 字符集的小写字母（“a”到“z”）或数字（“0”到“9”）组成。 -属性名称应该是描述性的和简洁的，并且长度不应超过 20 个字符。 - -### 类型系统 - -以下抽象数据类型可用于属性。 -这些类型中的每一种都可以由不同的事件格式和协议元数据字段以不同的方式表示。 -本规范为所有实现必须支持的每种类型定义了规范的字符串编码。 - -- `Boolean` - “true”或“false”的布尔值。 - - 字符串编码：区分大小写的`true` 或 `false`值。 -- `Integer` -范围在 -2,147,483,648 到 +2,147,483,647 （包含）之间的整数。 - 这是有符号 32 位二进制补码编码的范围。 - 事件格式不必使用此编码，但它们必须使用在此范围内的`Integer` 值。 - - 字符串编码: 符合 - [RFC 7159, 第 6 节](https://tools.ietf.org/html/rfc7159#section-6) - JSON 数字的整数部分 -- `String` - 允许的 Unicode 字符序列。 不允许使用以下字符： - - 范围 U+0000-U+001F 和 U+007F-U+009F（包含首尾）中的“控制字符”， - 因为大多数没有商定的含义，还有一些，例如 U+000A（换行符）， 在如 HTTP 头部之类的上下文中不可用。 - -[被 Unicode 标识为非字符的](http://www.unicode.org/faq/private_use.html#noncharacters) - 代码点。 - - 被 Unicode 标识为代理项的代码点, 范围 U+D800-U+DBFF 和 U+DC00-U+DFFF（包含首尾） - , 除非被合理的用作代理对. 因此（在 JSON 符号中） - “\uDEAD”是无效的，因为它是一个未配对的代理，而“\uD800\uDEAD”是合法的。 -- `Binary` - 字节序列. - - 字符串编码: 基于 - [RFC4648](https://tools.ietf.org/html/rfc4648) 的Base64 编码。 -- `URI` - 绝对统一资源标识符。 - - 字符串编码: - [RFC 3986 第 4.3 节](https://tools.ietf.org/html/rfc3986#section-4.3) - 中定义的 `Absolute URI` 。 -- `URI-reference` - 统一资源标识符引用。 - - 字符串编码: - [RFC 3986 第 4.1 节](https://tools.ietf.org/html/rfc3986#section-4.1) - 中定义的`URI-reference` 。 -- `Timestamp` - 使用公历的日期和时间表达式。 - - 字符串编码: [RFC 3339](https://tools.ietf.org/html/rfc3339) 。 - -所有上下文属性值必须是上面列出的类型之一。 -属性值可以表示为原生类型或规范字符串。 - -当强类型编程语言表示 CloudEvent 或任何扩展时， -必须能够在规范字符串编码与对应抽象类型的运行时/编程语言类型之间进行转换。 - -例如，在给定的实现中，`time` 属性可能由编程语言的本地时间类型表示， -但它必须是可设置提供 RFC3339 字符串的， -并且当映射到 HTTP 消息头时，它必须可转换为 RFC3339 字符串。 - -CloudEvents 协议绑定或事件格式实现同样必须能够 -在规范字符串编码与协议元数据字段中的对应数据类型之间进行转换。 - -`Timestamp` 类型的属性值确实可能以字符串形式路由通过多个跃点， -并且仅在生产者和最终消费者处实现为本地运行时/语言类型。 -`Timestamp` 类型也可以作为本机协议类型路由， -并且可以在生产者和消费者端映射到/从各自的语言/运行时类型，但永远不会转为字符串格式。 - -序列化机制的选择将决定上下文属性和事件数据将如何序列化。 -例如，在 JSON 序列化的情况下，上下文属性和事件数据可能都出现在同一个 JSON 对象中。 - -### 必要属性 - -下列属性必须自所有的 CloudEvents 中展示： +### Attribute Naming Convention + +The CloudEvents specifications define mappings to various protocols and +encodings, and the accompanying CloudEvents SDK targets various runtimes and +languages. Some of these treat metadata elements as case-sensitive while others +do not, and a single CloudEvent might be routed via multiple hops that involve a +mix of protocols, encodings, and runtimes. Therefore, this specification limits +the available character set of all attributes such that case-sensitivity issues +or clashes with the permissible character set for identifiers in common +languages are prevented. + +CloudEvents attribute names MUST consist of lower-case letters ('a' to 'z') or +digits ('0' to '9') from the ASCII character set. Attribute names SHOULD be +descriptive and terse and SHOULD NOT exceed 20 characters in length. + +### Type System + +The following abstract data types are available for use in attributes. Each of +these types MAY be represented differently by different event formats and in +protocol metadata fields. This specification defines a canonical +string-encoding for each type that MUST be supported by all implementations. + +- `Boolean` - a boolean value of "true" or "false". + - String encoding: a case-sensitive value of `true` or `false`. +- `Integer` - A whole number in the range -2,147,483,648 to +2,147,483,647 + inclusive. This is the range of a signed, 32-bit, twos-complement encoding. + Event formats do not have to use this encoding, but they MUST only use + `Integer` values in this range. + - String encoding: Integer portion of the JSON Number per + [RFC 7159, Section 6](https://tools.ietf.org/html/rfc7159#section-6) +- `String` - Sequence of allowable Unicode characters. The following characters + are disallowed: + - the "control characters" in the ranges U+0000-U+001F and U+007F-U+009F (both + ranges inclusive), since most have no agreed-on meaning, and some, such as + U+000A (newline), are not usable in contexts such as HTTP headers. + - code points + [identified as noncharacters by Unicode](http://www.unicode.org/faq/private_use.html#noncharacters). + - code points identifying Surrogates, U+D800-U+DBFF and U+DC00-U+DFFF, both + ranges inclusive, unless used properly in pairs. Thus (in JSON notation) + "\uDEAD" is invalid because it is an unpaired surrogate, while + "\uD800\uDEAD" would be legal. +- `Binary` - Sequence of bytes. + - String encoding: Base64 encoding per + [RFC4648](https://tools.ietf.org/html/rfc4648). +- `URI` - Absolute uniform resource identifier. + - String encoding: `Absolute URI` as defined in + [RFC 3986 Section 4.3](https://tools.ietf.org/html/rfc3986#section-4.3). +- `URI-reference` - Uniform resource identifier reference. + - String encoding: `URI-reference` as defined in + [RFC 3986 Section 4.1](https://tools.ietf.org/html/rfc3986#section-4.1). +- `Timestamp` - Date and time expression using the Gregorian Calendar. + - String encoding: [RFC 3339](https://tools.ietf.org/html/rfc3339). + +All context attribute values MUST be of one of the types listed above. +Attribute values MAY be presented as native types or canonical strings. + +A strongly-typed programming model that represents a CloudEvent or any extension +MUST be able to convert from and to the canonical string-encoding to the +runtime/language native type that best corresponds to the abstract type. + +For example, the `time` attribute might be represented by the language's native +_datetime_ type in a given implementation, but it MUST be settable providing an +RFC3339 string, and it MUST be convertible to an RFC3339 string when mapped to a +header of an HTTP message. + +A CloudEvents protocol binding or event format implementation MUST likewise be +able to convert from and to the canonical string-encoding to the corresponding +data type in the encoding or in protocol metadata fields. + +An attribute value of type `Timestamp` might indeed be routed as a string +through multiple hops and only materialize as a native runtime/language type at +the producer and ultimate consumer. The `Timestamp` might also be routed as a +native protocol type and might be mapped to/from the respective +language/runtime types at the producer and consumer ends, and never materialize +as a string. + +The choice of serialization mechanism will determine how the context attributes +and the event data will be serialized. For example, in the case of a JSON +serialization, the context attributes and the event data might both appear +within the same JSON object. + +### REQUIRED Attributes + +The following attributes are REQUIRED to be present in all CloudEvents: #### id -- 类型: `String` -- 描述: 标识一个事件。 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 - 如果重复的事件被重新发送（例如由于网络错误），它可能具有相同的 `id`。 - Consumers MAY assume that - 消费者可以假设具有相同`source` 和 `id`的事件是重复的。 -- 示例: - - 一个由生产者维护的事件计数器 - - 一个 UUID -- 约束条件: - - 必要的 - - 必须是非空字符串 - - 在生产者的范围内必须是唯一的 +- Type: `String` +- Description: Identifies the event. Producers MUST ensure that `source` + `id` + is unique for each distinct event. If a duplicate event is re-sent (e.g. due + to a network error) it MAY have the same `id`. Consumers MAY assume that + Events with identical `source` and `id` are duplicates. +- Examples: + - An event counter maintained by the producer + - A UUID +- Constraints: + - REQUIRED + - MUST be a non-empty string + - MUST be unique within the scope of the producer #### source -- 类型: `URI-reference` -- 描述: 标识事件发生的上下文背景。 这通常包括诸如事件源类型、发布事件的组织 - 或产生事件的过程等信息。URI 中编码的数据背后的确切语法和语义由事件生产者定义。 - - 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 - - 应用程序可以为每个不同的生产者分配一个唯一的`source`， - 这使得生成唯一 ID 变得容易，因为没有其他生产者将拥有相同的来源。 - 应用程序可以使用 UUIDs、URNs、DNS权威机构或特定于应用程序的方案来创建唯一的`source` 标识符。 - - 一个来源可以包括多个生产者。 - 在这种情况下，生产者必须协作以确保每个不同事件的 `source` + `id`都是唯一的。 - -- 约束条件: - - 必要的 - - 必须是非空 URI-reference - - 推荐使用 绝对 URI -- 示例 - - 具有 DNS 权限的 Internet 范围唯一 URI： +- Type: `URI-reference` +- Description: Identifies the context in which an event happened. Often this + will include information such as the type of the event source, the + organization publishing the event or the process that produced the event. The + exact syntax and semantics behind the data encoded in the URI is defined by + the event producer. + + Producers MUST ensure that `source` + `id` is unique for each distinct event. + + An application MAY assign a unique `source` to each distinct producer, which + makes it easy to produce unique IDs since no other producer will have the same + source. The application MAY use UUIDs, URNs, DNS authorities or an + application-specific scheme to create unique `source` identifiers. + + A source MAY include more than one producer. In that case the producers MUST + collaborate to ensure that `source` + `id` is unique for each distinct event. + +- Constraints: + - REQUIRED + - MUST be a non-empty URI-reference + - An absolute URI is RECOMMENDED +- Examples + - Internet-wide unique URI with a DNS authority. - https://github.com/cloudevents - mailto:cncf-wg-serverless@lists.cncf.io - - 具有 UUID 的通用唯一 URN： + - Universally-unique URN with a UUID: - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 - - 应用程序专有的标识符 + - Application-specific identifiers - /cloudevents/spec/pull/123 - /sensors/tn-1234567/alerts - 1-555-123-4567 #### specversion -- 类型: `String` -- 描述: 事件使用的 CloudEvents 规范的版本。 - 这让解释上下文环境更容易。 - 当引用这个版本的规范时，兼容的事件生产者必须使用 `1.0` 的值。 -- 约束条件: - - 必要的 - - 必须是非空字符串 +- Type: `String` +- Description: The version of the CloudEvents specification which the event + uses. This enables the interpretation of the context. Compliant event + producers MUST use a value of `1.0` when referring to this version of the + specification. +- Constraints: + - REQUIRED + - MUST be a non-empty string #### type -- 类型: `String` -- 描述: 该属性包含一个值，描述与原始事件相关的事件类型。 - 该属性通常用于路由、可观察性、策略实施等。其格式是生产者定义的，可能包括诸如 `type`版本之类的信息 - -从 - [入门文档-属性版本控制](primer.md#属性版本控制) 中获得更多信息 - -- 约束条件: - - 必要的 - - 必须是非空字符串 - - 应该以反向 DNS 名称作为前缀。该前缀域表明了定义此事件类型语义的组织。 -- 示例 +- Type: `String` +- Description: This attribute contains a value describing the type of event + related to the originating occurrence. Often this attribute is used for + routing, observability, policy enforcement, etc. The format of this is + producer defined and might include information such as the version of the + `type` - see + [Versioning of Attributes in the Primer](primer.md#versioning-of-attributes) + for more information. +- Constraints: + - REQUIRED + - MUST be a non-empty string + - SHOULD be prefixed with a reverse-DNS name. The prefixed domain dictates the + organization which defines the semantics of this event type. +- Examples - com.github.pull.create - com.example.object.delete.v2 -### 可选属性 +### OPTIONAL Attributes -下列属性在 CloudEvents 中是可选的. 在 -[符号约定](#notational-conventions) 中查看更多 OPTIONAL 定义的信息。 +The following attributes are OPTIONAL to appear in CloudEvents. See the +[Notational Conventions](#notational-conventions) section for more information +on the definition of OPTIONAL. #### datacontenttype -- 类型: `String` [RFC 2046](https://tools.ietf.org/html/rfc2046) -- 描述: `data`值的内容类型。 此属性使`data`能够承载任何类型的内容， - 因此格式和编码可能与所选事件格式的不同。 - 例如，使用 [JSON envelope](./json-format.md#3-envelope) - 格式呈现的事件可能在数据中携带 XML 的payload，这个属性可以用来通知消费者 - 设置"application/xml"。 - 关于`data`内容如何提供不同的`datacontenttype`的值的规则在事件格式规范中定义。 - 例如，JSON 事件格式定义了 [3.1 节](./json-format.md#31-handling-of-data)中的关系。 - 对于某些二进制模式协议绑定， - 此字段直接能映射到相应协议的内容类型的元数据属性上。 - 二进制模式和内容类型元数据映射的规范规则可以在各自的协议中找到。 - - 在某些事件格式中，可以省略 `datacontenttype` 属性。 - 例如，如果 JSON 格式的事件没有 `datacontenttype` 属性， - 则表示该`data`是符合“application/json”媒体类型的 JSON 值。 - 换句话说：一个没有 `datacontenttype` 的 JSON 格式的事件完全等同于 - 一个带有 `datacontenttype="application/json"`的事件。 - - 当将没有 `datacontenttype` 属性的事件消息转换为不同的格式或协议绑定时， - 目标 `datacontenttype` 应该显式设置为事件源的隐含或默认的 `datacontenttype`。 - -- 约束条件: - - 可选的 - - 若有则必须遵守 - [RFC 2046](https://tools.ietf.org/html/rfc2046) 制定的格式 -- 媒体类型示例 +- Type: `String` per [RFC 2046](https://tools.ietf.org/html/rfc2046) +- Description: Content type of `data` value. This attribute enables `data` to + carry any type of content, whereby format and encoding might differ from that + of the chosen event format. For example, an event rendered using the + [JSON envelope](./json-format.md#3-envelope) format might carry an XML payload + in `data`, and the consumer is informed by this attribute being set to + "application/xml". The rules for how `data` content is rendered for different + `datacontenttype` values are defined in the event format specifications; for + example, the JSON event format defines the relationship in + [section 3.1](./json-format.md#31-handling-of-data). + + For some binary mode protocol bindings, this field is directly mapped to the + respective protocol's content-type metadata property. Normative rules for the + binary mode and the content-type metadata mapping can be found in the + respective protocol + + In some event formats the `datacontenttype` attribute MAY be omitted. For + example, if a JSON format event has no `datacontenttype` attribute, then it is + implied that the `data` is a JSON value conforming to the "application/json" + media type. In other words: a JSON-format event with no `datacontenttype` is + exactly equivalent to one with `datacontenttype="application/json"`. + + When translating an event message with no `datacontenttype` attribute to a + different format or protocol binding, the target `datacontenttype` SHOULD be + set explicitly to the implied `datacontenttype` of the source. + +- Constraints: + - OPTIONAL + - If present, MUST adhere to the format specified in + [RFC 2046](https://tools.ietf.org/html/rfc2046) +- For Media Type examples see [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml) #### dataschema -- 类型: `URI` -- 描述: 标识 `data` 遵守的规范。 对模式的不兼容的更改应该由不同的 URI 体现。 在 - [入门文档-属性版本控制](primer.md#属性版本控制) - 中查看更多信息。 -- 约束条件: - - 可选的 - - 若有必须是非空的 URI +- Type: `URI` +- Description: Identifies the schema that `data` adheres to. Incompatible + changes to the schema SHOULD be reflected by a different URI. See + [Versioning of Attributes in the Primer](primer.md#versioning-of-attributes) + for more information. +- Constraints: + - OPTIONAL + - If present, MUST be a non-empty URI #### subject -- 类型: `String` -- 描述: 这个属性描述了事件生产者 (由`source`标识) 上下文环境中的主题信息。 - 在发布-订阅场景中，订阅者通常会订阅`source`发出的事件， - 但如果`source` 的上下文环境具有内部子结构， - 则单独的`source`标识符可能不足以作为任何指定事件的限定符。 - - 在上下文元数据中识别事件的主题（与仅在数据负载中相反） - 对于中间件无法解释`data` 内容的通用订阅过滤场景特别有用。 - 在上面的示例中，订阅者可能只对名称以“.jpg”或“.jpeg”结尾的blob感兴趣， - 此时`subject` 属性允许为该事件子集构建简单有效的字符串后缀过滤器。 - -- 约束条件: - - 可选的 - - 若有必须是非空字符串 -- 示例: - - 订阅者可能对在blob在blob存储容器中创建的时候感兴趣并订阅。 - 在这个场景下，事件`source`标示出订阅的范围（存储容器），`type` 标识出 - blob 创建" 这个事件，`id` 唯一标识出事件示例，以区分已创建同名blob的事件， - 而新创建的blob的名字可以放在`subject`属性中： +- Type: `String` +- Description: This describes the subject of the event in the context of the + event producer (identified by `source`). In publish-subscribe scenarios, a + subscriber will typically subscribe to events emitted by a `source`, but the + `source` identifier alone might not be sufficient as a qualifier for any + specific event if the `source` context has internal sub-structure. + + Identifying the subject of the event in context metadata (opposed to only in + the `data` payload) is particularly helpful in generic subscription filtering + scenarios where middleware is unable to interpret the `data` content. In the + above example, the subscriber might only be interested in blobs with names + ending with '.jpg' or '.jpeg' and the `subject` attribute allows for + constructing a simple and efficient string-suffix filter for that subset of + events. + +- Constraints: + - OPTIONAL + - If present, MUST be a non-empty string +- Example: + - A subscriber might register interest for when new blobs are created inside a + blob-storage container. In this case, the event `source` identifies the + subscription scope (storage container), the `type` identifies the "blob + created" event, and the `id` uniquely identifies the event instance to + distinguish separate occurrences of a same-named blob having been created; + the name of the newly created blob is carried in `subject`: - `source`: https://example.com/storage/tenant/container - `subject`: mynewfile.jpg #### time -- 类型: `Timestamp` -- 描述: 事件发生的时间戳。 - 如果无法确定发生的时间，则 CloudEvents 生产者可以将此属性设置为其他时间（例如当前时间）。 - 但是在这方面，同一`source`的所有生产者必须保持一致。 - 换句话说，要么它们都使用发生的实际时间，要么它们都使用相同的算法来确定所使用的值。 - -- 约束条件: - - 可选的 - - 若有则必须遵守 +- Type: `Timestamp` +- Description: Timestamp of when the occurrence happened. If the time of the + occurrence cannot be determined then this attribute MAY be set to some other + time (such as the current time) by the CloudEvents producer, however all + producers for the same `source` MUST be consistent in this respect. In other + words, either they all use the actual time of the occurrence or they all use + the same algorithm to determine the value used. +- Constraints: + - OPTIONAL + - If present, MUST adhere to the format specified in [RFC 3339](https://tools.ietf.org/html/rfc3339) -### 扩展上下文属性 - -CloudEvent 可以包含任意数量的具有不同名称的附加上下文属性，被称为"扩展属性"。 -扩展属性必须遵循相同的[命名约定](#属性命名约定)并使用与标准属性相同的 -[类型系统](#类型系统)。 -扩展属性在本规范中没有定义好的含义， -它们允许外部系统将元数据附加到事件，就像 HTTP 自定义头部一样。 - -扩展属性总是如标准属性一样，根据绑定规则进行序列化。 -然而，该规范不阻止扩展将事件属性值复制到消息的其他部分， -以便与也其它处理消息的非 CloudEvents 系统进行交互。 -如果复制的值与云事件序列化值不同，执行此操作的扩展规范应该指定接收者如何解释消息。 - -#### 定义扩展 - -在 -[CloudEvent-属性扩展](primer.md#CloudEvent-属性扩展) -查阅有关扩展使用和定义等相关信息。 - -扩展的定义应该完全定义属性的方方面面——例如 它的名称、类型、语义含义和可能的值。 -新的扩展定义应该使用一个足够描述性的名称来减少与其他扩展的名称冲突的机会。 -特别是，扩展作者应该检查[扩展文件](documented-extensions.md)中 -已知的扩展集——不仅是可能的名称冲突，还有相同目的冲突的扩展。 - -许多协议为发送者提供了包含额外元数据的能力，例如作为 HTTP 头部。 -虽然没有强制要求 CloudEvents 接受者处理和传递它们， -但建议接受者通过某种机制进行处理，以明确它们是非 CloudEvents 的元数据。 - -下面是一个示例，说明了 CloudEvents 对附加属性的需求。 -在许多物联网和企业用例中，事件可用于跨多种类型事件执行操作的serverless应用程序中。 -为了支持这样的用例，事件生产者需要向“上下文属性”添加额外的身份属性， -事件消费者可以使用这些属性将这个事件与其他事件相关联。 -如果此类身份属性恰好是事件“数据”的一部分， -则事件生产者还会将身份属性添加到“上下文属性”中， -以便事件消费者可以轻松访问此信息，而无需解码和检查事件数据。 -此类身份属性还可用于帮助中间网关确定如何路由事件。 - -## 事件数据 - -正如[数据](#数据)所定义的那样，CloudEvents 可以包括有关事件的特定域的信息。 -这些信息将被封装在`data`中。 - -- 描述: 事件负载。 本规范对该信息的类型不作任何限制。 - 它被编码为一种媒体格式，这种格式由`datacontenttype` 属性(如 application/json)指定， - 并在存在这些相应属性时遵循`dataschema`格式。 - It is encoded into a media format - -- 约束条件: - - 可选的 - -# 大小限制 - -在很多情况下，CloudEvents 将通过一个或多个通用中间人进行转发， -每个中间人都可能对转发事件的大小施加限制。 -CloudEvents 也可能直接被路由到消费者，如嵌入式设备， -这些设备是受存储或内存限制的，对单个大型事件表现不佳。 - -事件的“大小”是它的线路大小，包括在线路上为事件传输的每一位： -协议帧元数据、事件元数据和事件数据，基于所选的事件格式和所选的协议绑定。 - -如果应用程序配置需要跨不同协议路由事件或重新编码事件， -应用程序能使用的效率最低的协议和编码，都修腰符合这些大小限制： - -- 中间人转发的事件大小必须为 64 KB 或更小。 -- 消费者应该能接受大小至少为 64 KB 的事件。 - -为了方便，上述规则将允许生产者安全地发布最大 64KB 的事件。 -这里的安全意味着生产者期望事件被所有中间人接受并合理地转发。 -它是在任何特定消费者的控制之下，无论消费者是否由于本地考虑而选择接受或拒绝该大小的事件。 - -通常，CloudEvents 发布者应该通过避免将大型数据项嵌入到事件而使用事件有效链接到此类数据项， -来保持事件紧凑。 -从访问控制的角度来看，这种方法对更广泛的事件分布式化有帮助， -因为通过解析链接访问与事件相关的细节能实现差异化访问控制和选择性披露， -而不是将敏感详细数据直接嵌入到事件中。 - -# 隐私与安全 - -互操作性是本规范背后的主要驱动力， -实现此目标需要一些信息明确可用，这可能导致信息的泄漏。 - -考虑以下事项以防止信息意外泄漏，尤其是在利用第三方平台和通信网络时： - -- 上下文属性 - - 敏感信息不应在上下文属性中携带。 - - CloudEvent 生产者、消费者和中间人可以自查并记录下上下文属性。 - -- 数据 - - 特定的[事件数据](#事件数据) 应该被加密以限制对受信任方的可见性。 - 用于这种加密的机制是生产者和消费者之间的协议，不在本规范的讨论范围内。 - -- 协议绑定 - 应该采用协议级别的安全性机制来确保 CloudEvents 完成可信和安全的交换。 +### Extension Context Attributes + +A CloudEvent MAY include any number of additional context attributes with +distinct names, known as "extension attributes". Extension attributes MUST +follow the same [naming convention](#attribute-naming-convention) and use the +same [type system](#type-system) as standard attributes. Extension attributes +have no defined meaning in this specification, they allow external systems to +attach metadata to an event, much like HTTP custom headers. + +Extension attributes are always serialized according to binding rules like +standard attributes. However this specification does not prevent an extension +from copying event attribute values to other parts of a message, in order to +interact with non-CloudEvents systems that also process the message. Extension +specifications that do this SHOULD specify how receivers are to interpret +messages if the copied values differ from the cloud-event serialized values. + +#### Defining Extensions + +See +[CloudEvent Attributes Extensions](primer.md#cloudevent-attribute-extensions) +for additional information concerning the use and definition of extensions. + +The definition of an extension SHOULD fully define all aspects of the +attribute - e.g. its name, type, semantic meaning and possible values. New +extension definitions SHOULD use a name that is descriptive enough to reduce the +chances of name collisions with other extensions. In particular, extension +authors SHOULD check the [documented extensions](documented-extensions.md) +document for the set of known extensions - not just for possible name conflicts +but for extensions that might be of interest. + +Many protocols support the ability for senders to include additional metadata, +for example as HTTP headers. While a CloudEvents receiver is not mandated to +process and pass them along, it is RECOMMENDED that they do so via some +mechanism that makes it clear they are non-CloudEvents metadata. + +Here is an example that illustrates the need for additional attributes. In many +IoT and enterprise use cases, an event could be used in a serverless application +that performs actions across multiple types of events. To support such use +cases, the event producer will need to add additional identity attributes to the +"context attributes" which the event consumers can use to correlate this event +with the other events. If such identity attributes happen to be part of the +event "data", the event producer would also add the identity attributes to the +"context attributes" so that event consumers can easily access this information +without needing to decode and examine the event data. Such identity attributes +can also be used to help intermediate gateways determine how to route the +events. + +## Event Data + +As defined by the term [Data](#data), CloudEvents MAY include domain-specific +information about the occurrence. When present, this information will be +encapsulated within `data`. + +- Description: The event payload. This specification does not place any + restriction on the type of this information. It is encoded into a media format + which is specified by the `datacontenttype` attribute (e.g. application/json), + and adheres to the `dataschema` format when those respective attributes are + present. + +- Constraints: + - OPTIONAL + +# Size Limits + +In many scenarios, CloudEvents will be forwarded through one or more generic +intermediaries, each of which might impose limits on the size of forwarded +events. CloudEvents might also be routed to consumers, like embedded devices, +that are storage or memory-constrained and therefore would struggle with large +singular events. + +The "size" of an event is its wire-size and includes every bit that is +transmitted on the wire for the event: protocol frame-metadata, event metadata, +and event data, based on the chosen event format and the chosen protocol +binding. + +If an application configuration requires for events to be routed across +different protocols or for events to be re-encoded, the least efficient +protocol and encoding used by the application SHOULD be considered for +compliance with these size constraints: + +- Intermediaries MUST forward events of a size of 64 KByte or less. +- Consumers SHOULD accept events of a size of at least 64 KByte. + +In effect, these rules will allow producers to publish events up to 64KB in size +safely. Safely here means that it is generally reasonable to expect the event to +be accepted and retransmitted by all intermediaries. It is in any particular +consumer's control, whether it wants to accept or reject events of that size due +to local considerations. + +Generally, CloudEvents publishers SHOULD keep events compact by avoiding +embedding large data items into event payloads and rather use the event payload +to link to such data items. From an access control perspective, this approach +also allows for a broader distribution of events, because accessing +event-related details through resolving links allows for differentiated access +control and selective disclosure, rather than having sensitive details embedded +in the event directly. + +# Privacy and Security + +Interoperability is the primary driver behind this specification, enabling such +behavior requires some information to be made available _in the clear_ resulting +in the potential for information leakage. + +Consider the following to prevent inadvertent leakage especially when leveraging +3rd party platforms and communication networks: + +- Context Attributes + + Sensitive information SHOULD NOT be carried or represented in context + attributes. + + CloudEvent producers, consumers, and intermediaries MAY introspect and log + context attributes. + +- Data -# 示例 + Domain specific [event data](#event-data) SHOULD be encrypted to restrict + visibility to trusted parties. The mechanism employed for such encryption is + an agreement between producers and consumers and thus outside the scope of + this specification. + +- Protocol Bindings + + Protocol level security SHOULD be employed to ensure the trusted and secure + exchange of CloudEvents. + +# Example -以下示例展示了一个序列化为 JSON 的 CloudEvent： +The following example shows a CloudEvent serialized as JSON: ```JSON { From bf8a1be5675ee0601e8b636d26c00ead3a1e6329 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:31:08 +0800 Subject: [PATCH 52/60] Update README_CN.md Signed-off-by: JieDing --- README_CN.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README_CN.md b/README_CN.md index 64a4ee4f7..8c6145b7c 100644 --- a/README_CN.md +++ b/README_CN.md @@ -45,9 +45,9 @@ CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvent | Primer | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/primer.md) | [master](https://github.com/cloudevents/spec/blob/master/primer.md) | | Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | -对于初次接触CloudEvents的同学，可以通过阅读[入门文档](primer.md)增加对CloudEvents规范的目标和设计理念 +对于初次接触CloudEvents的同学，可以通过阅读[入门文档](primer_CN.md)增加对CloudEvents规范的目标和设计理念 的总体理解， -希望在最短时间内使用CloudEvents 规范的同学，可以直接阅读[核心规范](spec.md)。 +希望在最短时间内使用CloudEvents 规范的同学，可以直接阅读[核心规范](spec_CN.md)。 由于并非所有事件生产者都默认生产符合CloudEvents规范的事件，因此可以用[CloudEvents适配器](https://github.com/cloudevents/spec/blob/master/adapters.md) 来将现有的事件与CloudEvents做适配。 @@ -74,8 +74,8 @@ CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvent ## 步骤 -CloudEvents项目 [旨在](primer.md#设计目标)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 -的[标准](spec.md)。 +CloudEvents项目 [旨在](primer_CN.md#设计目标)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 +的[标准](spec_CN.md)。 为了完成这个目标，这个项目必须描述： From 10fd719ca1e2a123d56c43d4a803d85531b6a146 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:34:39 +0800 Subject: [PATCH 53/60] Update primer_CN.md Signed-off-by: JieDing --- primer_CN.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/primer_CN.md b/primer_CN.md index a5382f71f..5b5b77bc6 100644 --- a/primer_CN.md +++ b/primer_CN.md @@ -40,7 +40,7 @@ Serverless相关技术并为CNCF推荐相关领域的未来发展计划的。工 ## CloudEvents-概念 -一个[事件](spec.md#事件)包含了[事件发生](spec.md#发生)的上下文和相关数据。 +一个[事件](spec_CN.md#事件)包含了[事件发生](spec_CN.md#发生)的上下文和相关数据。 事件的相关数据可以用来唯一标识一件事件的发生。 事件代表了已发生的事实，因此它并不包含任何目的地相关信息，但消息能够传达事件内容，从而将事件数据 @@ -98,7 +98,7 @@ CloudEvents的核心规范中定义了一组称之为属性的元数据， 为了提升系统间的互操作性，是否以及如何实现批处理将由协议自己决定。 相关详细信息可以在协议绑定或协议规范中找到。 成批的CloudEvents并没有语义，也没有排序。 -[中间人](spec.md#中间人)可以添加或删除批处理以及将事件分配给不同的批处理。 +[中间人](spec_CN.md#中间人)可以添加或删除批处理以及将事件分配给不同的批处理。 ### 非目标 @@ -135,9 +135,9 @@ CloudEvents 应该增加互操作性并解耦事件的生产者和消费者。 CloudEvents 规范集定义了四种有助于形成分层架构模型的不同类型的协议元素。 基本规范定义了一个抽象信息模型，该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 -1. [基本规范](spec.md) 定义了一个抽象信息模型， +1. [基本规范](spec_CN.md) 定义了一个抽象信息模型， 该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 -2. [扩展属性](./spec.md#扩展上下文属性) +2. [扩展属性](./spec_CN.md#扩展上下文属性) 添加了特定于用例且可能重叠的扩展属性集和相关规则，如支持不同的追踪标准的规则。 3. 事件格式编码,如 [JSON](json-format.md), 定义了基本规范的信息模型与所选扩展的编码方式， 以将其映射到应用程序协议的头部和负载元素。 @@ -428,9 +428,9 @@ CloudEvents的努力不应成为认可或推广项目或产品专有协议的工 事件是否可通过中间件消费取决于生产者的选择。 - 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec.md#生产者)的角色， - 当它根据事件采取行动时可以扮演[消费者](spec.md#消费者)的角色， - 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec.md#中间人)的角色。 + 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec_CN.md#生产者)的角色， + 当它根据事件采取行动时可以扮演[消费者](spec_CN.md#消费者)的角色， + 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec_CN.md#中间人)的角色。 4. 框架和其他抽象使与事件平台基础设施间的交互更简单， 并且通常为多个事件平台基础设施提供公共 API 区域。 From 39a1356d825ba1c1dcefcf35988972245fe81803 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:37:00 +0800 Subject: [PATCH 54/60] Update spec_CN.md Signed-off-by: JieDing --- spec_CN.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec_CN.md b/spec_CN.md index 7c9c1a8cd..e27e009d3 100644 --- a/spec_CN.md +++ b/spec_CN.md @@ -35,7 +35,7 @@ CloudEvents是一个以通用格式来描述事件数据的标准。它提供了 所有实现都必须支持 [JSON 格式](json-format.md)。 有关规范背后的历史、开发和设计原理等更多信息， -请参阅 CloudEvents [入门文档](primer.md)。 +请参阅 CloudEvents [入门文档](primer_CN.md)。 ## 符号和术语 @@ -269,7 +269,7 @@ CloudEvents 协议绑定或事件格式实现同样必须能够 - 描述: 该属性包含一个值，描述与原始事件相关的事件类型。 该属性通常用于路由、可观察性、策略实施等。其格式是生产者定义的，可能包括诸如 `type`版本之类的信息 -从 - [入门文档-属性版本控制](primer.md#属性版本控制) 中获得更多信息 + [入门文档-属性版本控制](primer_CN.md#属性版本控制) 中获得更多信息 - 约束条件: - 必要的 @@ -318,7 +318,7 @@ CloudEvents 协议绑定或事件格式实现同样必须能够 - 类型: `URI` - 描述: 标识 `data` 遵守的规范。 对模式的不兼容的更改应该由不同的 URI 体现。 在 - [入门文档-属性版本控制](primer.md#属性版本控制) + [入门文档-属性版本控制](primer_CN.md#属性版本控制) 中查看更多信息。 - 约束条件: - 可选的 @@ -377,7 +377,7 @@ CloudEvent 可以包含任意数量的具有不同名称的附加上下文属性 #### 定义扩展 在 -[CloudEvent-属性扩展](primer.md#CloudEvent-属性扩展) +[CloudEvent-属性扩展](primer_CN.md#CloudEvent-属性扩展) 查阅有关扩展使用和定义等相关信息。 扩展的定义应该完全定义属性的方方面面——例如 它的名称、类型、语义含义和可能的值。 From 31338518bdd66ae3ca1e710d0d8bd2de46d53b43 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:52:55 +0800 Subject: [PATCH 55/60] Create README_CN.md Signed-off-by: JieDing --- Chinese Manual/README_CN.md | 132 ++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 Chinese Manual/README_CN.md diff --git a/Chinese Manual/README_CN.md b/Chinese Manual/README_CN.md new file mode 100644 index 000000000..8c6145b7c --- /dev/null +++ b/Chinese Manual/README_CN.md @@ -0,0 +1,132 @@ +# CloudEvents 中文手册 + +![CloudEvents logo](https://github.com/cncf/artwork/blob/master/projects/cloudevents/horizontal/color/cloudevents-horizontal-color.png) + +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. + +事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 + +对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。它同样限制了那些用来帮助事件数据完成 +跨环境传输的库(如SDKs)，工具(如事件路由器)和基础设施(如事件追踪系统)的发展。总体来看，这种匮乏严重阻碍了事件数据的 +可移植性和生产力。 + +CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 + +CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvents被[云原生计算基金会](https://cncf.io) (CNCF)持有， +在[2018/05/15](https://docs.google.com/presentation/d/1KNSv70fyTfSqUerCnccV7eEC_ynhLsm9A_kjnlmU_t0/edit#slide=id.g37acf52904_1_41) +被选为云原生沙箱级项目。 + +## CloudEvents 文件 + +现有文件如下: + +| | 最新版本 | 工作草稿 | +| :---------------------------- | :----------------------------------------------------------------------------: | :---------------------------------------------------------------------------------: | +| **核心标准:** | +| CloudEvents | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/spec.md) | [master](https://github.com/cloudevents/spec/blob/master/spec.md) | +| | +| **可选标准:** | +| AMQP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/amqp-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-protocol-binding.md) | +| AVRO Event Format | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/avro-format.md) | [master](https://github.com/cloudevents/spec/blob/master/avro-format.md) | +| HTTP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/http-protocol-binding.md) | +| JSON Event Format | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/json-format.md) | [master](https://github.com/cloudevents/spec/blob/master/json-format.md) | +| Kafka Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/kafka-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/kafka-protocol-binding.md) | +| MQTT Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/mqtt-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/mqtt-protocol-binding.md) | +| NATS Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/nats-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/nats-protocol-binding.md) | +| Web hook | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md) | [master](https://github.com/cloudevents/spec/blob/master/http-webhook.md) | +| | +| **附加文件:** | +| CloudEvents Adapters | - | [master](https://github.com/cloudevents/spec/blob/master/adapters.md) | +| CloudEvents SDK Requirements | - | [master](https://github.com/cloudevents/spec/blob/master/SDK.md) | +| Documented Extensions | - | [master](https://github.com/cloudevents/spec/blob/master/documented-extensions.md) | +| Primer | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/primer.md) | [master](https://github.com/cloudevents/spec/blob/master/primer.md) | +| Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | + +对于初次接触CloudEvents的同学，可以通过阅读[入门文档](primer_CN.md)增加对CloudEvents规范的目标和设计理念 +的总体理解， +希望在最短时间内使用CloudEvents 规范的同学，可以直接阅读[核心规范](spec_CN.md)。 + +由于并非所有事件生产者都默认生产符合CloudEvents规范的事件，因此可以用[CloudEvents适配器](https://github.com/cloudevents/spec/blob/master/adapters.md) +来将现有的事件与CloudEvents做适配。 + +## SDKs + +除了上述文档，我们还提供了[SDK 提议](SDK.md)以及一些编程语言的SDK： + +- [CSharp](https://github.com/cloudevents/sdk-csharp) +- [Go](https://github.com/cloudevents/sdk-go) +- [Java](https://github.com/cloudevents/sdk-java) +- [Javascript](https://github.com/cloudevents/sdk-javascript) +- [Python](https://github.com/cloudevents/sdk-python) + +## 社区 + +在社区里，你可以了解到更多致力于搭建一个动态、云原生的生态系统的成员和组织。 +他们不断尝试提升现有系统和CloudEvents间的互操作性和兼容性。 + +- [贡献者](community/contributors.md): + 是指那些帮助我们制定规范或是积极活跃在CloudEvents规范相关工作的成员和组织。 +- 即将推出: [demos & open source](community/README.md) -- + 如果你希望向我们分享关于你对CloudEvents的使用，请通过提交PR让我们看到。 + +## 步骤 + +CloudEvents项目 [旨在](primer_CN.md#设计目标)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 +的[标准](spec_CN.md)。 + +为了完成这个目标，这个项目必须描述： + +- 一系列能够提升互操作性的用来描述事件的属性 +- 一个或多个通用架构，这些架构必须是当下活跃的或是正在计划被完成的 +- 事件是如何在一种或多种协议下从生产者传输到消费者的 +- 识别并解决任何能提升互操作性的问题 +## 联系方式 + +邮件联系方式如下: + +- 发送EMail至: [cncf-cloudevents](mailto:cncf-cloudevents@lists.cncf.io) +- 订阅地址: https://lists.cncf.io/g/cncf-cloudevents +- 存档地址: https://lists.cncf.io/g/cncf-cloudevents/topics + +## 会议时间 + +会议日期请查看 [CNCF 公开活动日历](https://www.cncf.io/community/calendar/). +CloudEvents规范由 +[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 开发完成。 +这个工作组每周四的上午9点(美国-太平洋时间)通过Zoom开展视频会议。 +通过 PC, Mac, Linux, iOS or Android来参加活动: https://zoom.us/my/cncfserverlesswg + +或者通过 iPhone one-tap : + + US: +16465588656,,3361029682# or +16699006833,,3361029682# + +或者电话接入: + + Dial: + US: +1 646 558 8656 (US Toll) or +1 669 900 6833 (US Toll) + or +1 855 880 1246 (Toll Free) or +1 877 369 0926 (Toll Free) + +会议 ID: 336 102 9682 + +国际号码接入: +https://zoom.us/zoomconference?m=QpOqQYfTzY_Gbj9_8jPtsplp1pnVUKDr + +世界时区转化器: +http://www.thetimezoneconverter.com/?t=9:00%20am&tz=San%20Francisco& + +## 会议记录 + +历史会议记录在 +[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) +查看。 + +历史会议录像在 +[这里](https://www.youtube.com/playlist?list=PLj6h78yzYM2Ph7YoBIgsZNW_RGJvNlFOt) +查看。 + +工作组会定期举办与主流会议一致的线下会议。查看[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) +了解更多未来计划。 + From 68cab31b9cd3639beddbd90c20248f3a30564990 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:53:32 +0800 Subject: [PATCH 56/60] Delete README_CN.md Signed-off-by: JieDing --- README_CN.md | 132 --------------------------------------------------- 1 file changed, 132 deletions(-) delete mode 100644 README_CN.md diff --git a/README_CN.md b/README_CN.md deleted file mode 100644 index 8c6145b7c..000000000 --- a/README_CN.md +++ /dev/null @@ -1,132 +0,0 @@ -# CloudEvents 中文手册 - -![CloudEvents logo](https://github.com/cncf/artwork/blob/master/projects/cloudevents/horizontal/color/cloudevents-horizontal-color.png) - -Declaration： This manual aims to provide a fast and brief introduction of CloudEvents -in Chinese for people who are new to CloudEvents. -Most of the content is translated from the original English version. -It is strongly recommended to read the English version if you find anything lost in translation. - -事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 - -对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。它同样限制了那些用来帮助事件数据完成 -跨环境传输的库(如SDKs)，工具(如事件路由器)和基础设施(如事件追踪系统)的发展。总体来看，这种匮乏严重阻碍了事件数据的 -可移植性和生产力。 - -CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 - -CloudEvents 收获了从主流云厂商到SaaS公司的广泛关注。CloudEvents被[云原生计算基金会](https://cncf.io) (CNCF)持有， -在[2018/05/15](https://docs.google.com/presentation/d/1KNSv70fyTfSqUerCnccV7eEC_ynhLsm9A_kjnlmU_t0/edit#slide=id.g37acf52904_1_41) -被选为云原生沙箱级项目。 - -## CloudEvents 文件 - -现有文件如下: - -| | 最新版本 | 工作草稿 | -| :---------------------------- | :----------------------------------------------------------------------------: | :---------------------------------------------------------------------------------: | -| **核心标准:** | -| CloudEvents | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/spec.md) | [master](https://github.com/cloudevents/spec/blob/master/spec.md) | -| | -| **可选标准:** | -| AMQP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/amqp-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/amqp-protocol-binding.md) | -| AVRO Event Format | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/avro-format.md) | [master](https://github.com/cloudevents/spec/blob/master/avro-format.md) | -| HTTP Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/http-protocol-binding.md) | -| JSON Event Format | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/json-format.md) | [master](https://github.com/cloudevents/spec/blob/master/json-format.md) | -| Kafka Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/kafka-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/kafka-protocol-binding.md) | -| MQTT Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/mqtt-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/mqtt-protocol-binding.md) | -| NATS Protocol Binding | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/nats-protocol-binding.md) | [master](https://github.com/cloudevents/spec/blob/master/nats-protocol-binding.md) | -| Web hook | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md) | [master](https://github.com/cloudevents/spec/blob/master/http-webhook.md) | -| | -| **附加文件:** | -| CloudEvents Adapters | - | [master](https://github.com/cloudevents/spec/blob/master/adapters.md) | -| CloudEvents SDK Requirements | - | [master](https://github.com/cloudevents/spec/blob/master/SDK.md) | -| Documented Extensions | - | [master](https://github.com/cloudevents/spec/blob/master/documented-extensions.md) | -| Primer | [v1.0](https://github.com/cloudevents/spec/blob/v1.0/primer.md) | [master](https://github.com/cloudevents/spec/blob/master/primer.md) | -| Proprietary Specifications | - | [master](https://github.com/cloudevents/spec/blob/master/proprietary-specs.md) | - -对于初次接触CloudEvents的同学，可以通过阅读[入门文档](primer_CN.md)增加对CloudEvents规范的目标和设计理念 -的总体理解， -希望在最短时间内使用CloudEvents 规范的同学，可以直接阅读[核心规范](spec_CN.md)。 - -由于并非所有事件生产者都默认生产符合CloudEvents规范的事件，因此可以用[CloudEvents适配器](https://github.com/cloudevents/spec/blob/master/adapters.md) -来将现有的事件与CloudEvents做适配。 - -## SDKs - -除了上述文档，我们还提供了[SDK 提议](SDK.md)以及一些编程语言的SDK： - -- [CSharp](https://github.com/cloudevents/sdk-csharp) -- [Go](https://github.com/cloudevents/sdk-go) -- [Java](https://github.com/cloudevents/sdk-java) -- [Javascript](https://github.com/cloudevents/sdk-javascript) -- [Python](https://github.com/cloudevents/sdk-python) - -## 社区 - -在社区里，你可以了解到更多致力于搭建一个动态、云原生的生态系统的成员和组织。 -他们不断尝试提升现有系统和CloudEvents间的互操作性和兼容性。 - -- [贡献者](community/contributors.md): - 是指那些帮助我们制定规范或是积极活跃在CloudEvents规范相关工作的成员和组织。 -- 即将推出: [demos & open source](community/README.md) -- - 如果你希望向我们分享关于你对CloudEvents的使用，请通过提交PR让我们看到。 - -## 步骤 - -CloudEvents项目 [旨在](primer_CN.md#设计目标)制定一个能够提升不同事件系统(如生产者和消费者)之间互操作性和兼容性 -的[标准](spec_CN.md)。 - -为了完成这个目标，这个项目必须描述： - -- 一系列能够提升互操作性的用来描述事件的属性 -- 一个或多个通用架构，这些架构必须是当下活跃的或是正在计划被完成的 -- 事件是如何在一种或多种协议下从生产者传输到消费者的 -- 识别并解决任何能提升互操作性的问题 -## 联系方式 - -邮件联系方式如下: - -- 发送EMail至: [cncf-cloudevents](mailto:cncf-cloudevents@lists.cncf.io) -- 订阅地址: https://lists.cncf.io/g/cncf-cloudevents -- 存档地址: https://lists.cncf.io/g/cncf-cloudevents/topics - -## 会议时间 - -会议日期请查看 [CNCF 公开活动日历](https://www.cncf.io/community/calendar/). -CloudEvents规范由 -[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 开发完成。 -这个工作组每周四的上午9点(美国-太平洋时间)通过Zoom开展视频会议。 -通过 PC, Mac, Linux, iOS or Android来参加活动: https://zoom.us/my/cncfserverlesswg - -或者通过 iPhone one-tap : - - US: +16465588656,,3361029682# or +16699006833,,3361029682# - -或者电话接入: - - Dial: - US: +1 646 558 8656 (US Toll) or +1 669 900 6833 (US Toll) - or +1 855 880 1246 (Toll Free) or +1 877 369 0926 (Toll Free) - -会议 ID: 336 102 9682 - -国际号码接入: -https://zoom.us/zoomconference?m=QpOqQYfTzY_Gbj9_8jPtsplp1pnVUKDr - -世界时区转化器: -http://www.thetimezoneconverter.com/?t=9:00%20am&tz=San%20Francisco& - -## 会议记录 - -历史会议记录在 -[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) -查看。 - -历史会议录像在 -[这里](https://www.youtube.com/playlist?list=PLj6h78yzYM2Ph7YoBIgsZNW_RGJvNlFOt) -查看。 - -工作组会定期举办与主流会议一致的线下会议。查看[这里](https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#) -了解更多未来计划。 - From 3764eff9bfee32e348f9ee5406d063e5ded36761 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:53:54 +0800 Subject: [PATCH 57/60] Create primer_CN.md Signed-off-by: JieDing --- Chinese Manual/primer_CN.md | 704 ++++++++++++++++++++++++++++++++++++ 1 file changed, 704 insertions(+) create mode 100644 Chinese Manual/primer_CN.md diff --git a/Chinese Manual/primer_CN.md b/Chinese Manual/primer_CN.md new file mode 100644 index 000000000..5b5b77bc6 --- /dev/null +++ b/Chinese Manual/primer_CN.md @@ -0,0 +1,704 @@ +# CloudEvents 入门文档 - 1.0 版本 + +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. + +## 摘要 + +这份非技术规范文档用来为你提供关于CloudEvents规范的总体概览。它补充了CloudEvents规范的相关背景 +以及在制定 本规范时的历史和设计理念。这样，CloudEvents的核心规范就只需要关注Events规范的技术细节， +而不用过多地关心背景相关内容。 + +## 目录 + +- [历史](#历史) +- [CloudEvents 概念](#CloudEvents-概念) +- [设计目标](#设计目标) +- [架构](#架构) +- [属性版本控制](#属性版本控制) +- [CloudEvent 属性](#CloudEvent-属性) +- [CloudEvent 属性扩展](#CloudEvent-属性扩展) +- [生产 CloudEvents](#生产CloudEvents) +- [合格的协议与编码](#合格的协议与编码) +- [专有的协议和编码](#专有的协议与编码) +- [现有技术](#现有技术) +- [角色](#角色) +- [价值主张](#价值主张) +- [现有的数据格式](#现有的数据格式) + +## 历史 + +[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 是由 CNCF的 +[技术监管委员会](https://github.com/cncf/toc) 成立，用于研究 +Serverless相关技术并为CNCF推荐相关领域的未来发展计划的。工作组其中一项建议就是研究创建一种通用事件格式， +用于提升不同云厂商间函数的可移植性和事件流处理的互操作性。就此，CloudEvents应运而生。 + +尽管CloudEvents起初是作为Serverless工作组的项目进行的，但随着CloudEvents规范完成它v0.1版本的里程碑， +技术监管委员会批准了CloudEvents作为一个新的独立的CNCF沙箱级项目。 + +## CloudEvents-概念 + +一个[事件](spec_CN.md#事件)包含了[事件发生](spec_CN.md#发生)的上下文和相关数据。 +事件的相关数据可以用来唯一标识一件事件的发生。 + +事件代表了已发生的事实，因此它并不包含任何目的地相关信息，但消息能够传达事件内容，从而将事件数据 +从源头传输到指定的目的地。 + +### 事件使用 + +事件通常在服务器端代码中使用来连接不同的系统，其中一个系统中的状态变化会导致代码在另一个系统中执行。 +比如，一个事件源，可能会在收到某个外部信号(如HTTP或RPC)或观察到状态变化(如IoT传感器数据变化或不活跃) +时，生产一个事件。 + +为了更好地解释一个系统如何使用CloudEvents，下图展示了一个从事件源生产的事件是如何触发一个行为的。 + +![alt text](source-event-action.png "A box representing the source with +arrow pointing to a box representing the action. The arrow is annotated with +'e' for event and 'protocol'.") + +事件源生产了一条封装了基于某种协议的事件数据的消息。 +当载有事件的消息到达目的地时，会触发一个使用了事件数据的行为函数。 + +一个事件源是那些允许暂存和测试实例的源类型的特定实例。 +某个特定源类型的开源软件可能由多个公司或提供商部署。 + +事件可以通过各种行业标准协议（如HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或 +平台/供应商专有协议（AWS Kinesis、Azure Event Grid）传输。 + +一个操作函数能够处理那些定义了行为或影响的事件，这些行为和效果由来自特定源的特定事件触发而来。 +虽然超出了规范的范围，但生成事件的目的通常是让其他系统能够轻松地对它们无法控制的源中的更改做出反应。 +源和操作通常由不同的开发人员构建。 +通常，源是托管服务，而操作是serverless函数（如 AWS Lambda 或 Google Cloud Functions）中 +的自定义代码。 + +## 设计目标 + +CloudEvents 通常用于分布式系统，以允许服务在开发过程中松耦合，独立部署，方便之后连接以创建新的应用程序。 + +CloudEvents 规范的目标是定义允许服务生产或消费事件的事件系统的互操作性， +其中生产者和消费者可以独立开发和部署。 生产者可以在没有消费者监听时就生成事件， +消费者也可以表达对尚未生成的事件或事件类的兴趣。值得注意的是，这项工作产生的规范侧重于事件格式的互操作性 +以及它在通过各种协议（例如 HTTP）发送时的显示方式。我们不关注事件生产者或事件消费者的处理模型。 + +CloudEvents的核心规范中定义了一组称之为属性的元数据， +它们描述了在系统之间传输的事件以及这些元数据片段应如何显示在该消息中。 +这些元数据是，将请求路由到适当组件并帮助该组件正确处理事件所需的最小信息集。 +因此，某些事件本身的数据可能会作为 CloudEvent 属性集的一部分而被复制， +但这样做仅是为了能够正确传递和处理消息。那些不用于该目的的数据应放置在事件（数据）本身中。 + +此外，本规范中假设协议层所需的用来将消息传递到目标系统的元数据应完全由协议处理， +因此不包含在 CloudEvents 属性中。 有关更多详细信息，请参阅[非目标](#非目标)部分。 + +除了这些属性的定义之外，规范还描述了关于如何序列化 +不同格式（例如 JSON）和协议（例如 HTTP、AMQP、Kafka）的事件。 + +一些协议本身支持将多个事件批处理到单个 API 的调用中。 +为了提升系统间的互操作性，是否以及如何实现批处理将由协议自己决定。 +相关详细信息可以在协议绑定或协议规范中找到。 +成批的CloudEvents并没有语义，也没有排序。 +[中间人](spec_CN.md#中间人)可以添加或删除批处理以及将事件分配给不同的批处理。 + +### 非目标 + +以下内容不在本规范的范围之内： + +- 函数的构建和调用过程 +- 特定语言的运行时 APIs +- 选择单一身份认证或访问控制的系统 +- 包含协议级路由信息 +- 事件持久化过程 + +就连那些刚接触 CloudEvents 概念的人都会建议 +CloudEvents 规范不应包括协议级路由信息（例如，将事件发送到的目标的URL）。 +经过深思熟虑，工作组得出的结论是，CloudEvents规范中不需要路由信息： +因为任何现有的协议（例如 HTTP、MQTT、XMPP 或 Pub/Sub 总线）都已经定义了路由语义。 +例如，CloudEvents [HTTP 绑定](http-protocol-binding.md) 规定了头部和请求正文内容。 +CloudEvents 不需要在规范中包含目标 URL 即可与 HTTP 兼容；HTTP 规范已经在 +[请求行](https://tools.ietf.org/html/rfc2616#section-5.1) 中包含了所需的目标URL。 + +路由信息不仅是多余的，而且是有害的。 +CloudEvents 应该增加互操作性并解耦事件的生产者和消费者。 +禁止来自事件格式的路由信息允许将 CloudEvents 重新传送到新的行为，或通过包含多个通道的复杂中继传送。 +例如，如果 Webhook 地址不可用，则用于 Webhook 的 CloudEvent 应可传送到死信队列。 +死信队列应该能够将事件传送给原始事件发射者从未想象过的新的行为上。 + +在系统内和跨系统生产和消费的 CloudEvent能够触发产生价值的行为。 +因此，对于调试或复制的目的而言，存档和或重放事件可能很有价值。 +但是，持久化事件会删除传输期间可用的上下文信息，例如生产者的身份和权利、保真验证机制或机密性保护。 +此外，持久化会增加满足用户需求的复杂性和挑战。 +例如，出于加密或签名目的重复使用私钥会增加攻击者可用的信息，从而降低安全性。 +因此我们推测，可以定义有助于满足持久性要求的属性，但这些属性可能随着行业最佳实践和进步而不断发展。 + +## 架构 +CloudEvents 规范集定义了四种有助于形成分层架构模型的不同类型的协议元素。 +基本规范定义了一个抽象信息模型，该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 + +1. [基本规范](spec_CN.md) 定义了一个抽象信息模型， + 该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 +2. [扩展属性](./spec_CN.md#扩展上下文属性) + 添加了特定于用例且可能重叠的扩展属性集和相关规则，如支持不同的追踪标准的规则。 +3. 事件格式编码,如 [JSON](json-format.md), 定义了基本规范的信息模型与所选扩展的编码方式， + 以将其映射到应用程序协议的头部和负载元素。 +4. 协议绑定, 如. [HTTP协议绑定](http-protocol-binding.md), + 在HTTP to HTTP的情况下， + 定义了 CloudEvent 如何绑定到应用程序协议的传输层 。 + 协议绑定不限制传输层的使用方式，这意味着 HTTP绑定可用于任何 HTTP方法以及请求和响应消息。 + +为了确保更广泛的互操作性，CloudEvents规范集为使用专有应用协议的事件传输提供了特定约束。 +[HTTP Webhook](http-webhook.md)规范并非特定于 CloudEvents， +而是可用于将任何类型的单向事件和通知发布到符合标准的 HTTP 端点。 +但是，由于其他地方缺乏此类规范，因此 CloudEvents 需要对其进行定义。 + +### 协议错误处理 + +CloudEvents 规范在很大程度上并未规定与 CloudEvents 的创建或处理相关联的处理模型。 +因此，如果在处理 CloudEvent 过程中出现错误， +请使用正常的协议级错误处理机制进行处理。 + +## 属性版本控制 + +对于某些 CloudEvents 属性，由其值引用的实体或数据模型可能会随时间变化。 +例如，`dataschema`可能引用模式文档的一个特定版本。 +通常，这些属性值会通过将一些特定于版本的字符串作为其值的一部分来区分每个变体。 +例如，可能会加入版本号 (v1, v2) 或日期 (2018-01-01)来区分。 + +CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强制使用版本字符串。 +是否使用完全取决于每个事件生产者。 +但是，当使用特定版本的字符串时，每当其值发生变化时都应注意， +因为事件消费者可能依赖于现有值，因此更改可能被解释为“破坏性更改”。 +应该在生产者和消费者之间建立某种形式的通信，以确保事件消费者知道能使用哪些可能的值。 +通常，这也适用于所有 CloudEvents 属性。 + +## CloudEvent-属性 + +本节介绍了与CloudEvent 属性相关的其他背景和设计要点。 + +### id + +`id` 属性是一个在同一事件源下所有事件中用来标识事件唯一的值 +（其中每个事件源由其 CloudEvents `source`属性唯一标识）。 +虽然`id`使用的确切值是生产者定义的， +但必须要确保来自单个事件源的 CloudEvents 消费者不会有两个事件共享相同的 id 值。 +唯一的例外是如果支持事件的重播，在这些情况下，可以使用 id 来检测这一点。 + +由于一次事件的发生可能导致生成多个cloud event， +在所有这些事件都来自同一事件源的情况下， +生成的每个 CloudEvent 将具有唯一的 `id`。 +以创建数据库条目为例，这一事件的发生可能会生成一个类型为 create 的 CloudEvent +和一个类型为 write 的 CloudEvent。 +这两个 CloudEvents 各自都有一个唯一的 ID。 +如果需要在这两个 CloudEvent 之间建立某种关联以表明它们都与同一事件相关， +那么可以使用 CloudEvent 中的一些附加数据来实现该目的。 + +从这方面来看，虽然事件生产者对`id`的使用可能是某个随机字符串， +或者在其它上下文中具有某种语义的字符串， +但对于此 CloudEvent 属性而言，这些含义并不成立， +因此本规范不建议将 `id` 用于除了唯一性检查之外的其它目的。 + +## CloudEvent-属性扩展 + +为了实现规范的设计目标， +规范作者将尝试限制他们在 CloudEvents 中定义的元数据属性的数量。 +为此，该项目定义的属性将分为以下三类： + +- 必要属性 +- 可选属性 +- 扩展属性 + +正如类别名称所暗示的那样， +“必要”属性是工作组认为在任何情况下，对所有事件都至关重要的属性， +而“可选”属性将在大多数情况下使用。 这些情况下的两个属性都在本规范中定义了出来。 + +工作组考虑到某些属性不够常见而不能归入上述两个类别， +但此类属性的良好定义仍会使系统间的互操作性级别受益， +因此将这些属性放入了“扩展”类别并记录在[扩展文档](documented-extensions.md)中， +本规范定义了这些扩展属性在 CloudEvent 中的显示方式。 + +在确定提议的属性属于哪个类别时， +工作组使用现有的用例和用户故事来解释它们的基本原理和需求。 +相关信息将添加到本文档的[现有技术](#现有技术)部分。 + +CloudEvent 规范的扩展属性是需要包含的附加元数据，它们能确保正确的路由和正确处理CloudEvent。 +用于其它目的的附加元数据， +即那些与事件本身相但在 CloudEvent 的传输或处理中不需要的元数据， +应改为放置在事件 (`data`)的扩展点内。 + +扩展属性应保持最少，以确保 CloudEvent 可以正确序列化和传输。 +事件生产者应该考虑在向 CloudEvent 添加扩展时可能遇到的技术限制。 +例如，[HTTP Binary Mode](http-protocol-binding.md#31-binary-content-mode) +使用 HTTP 头来传输元数据； +大多数 HTTP 服务器会拒绝包含过多 HTTP 头部数据的请求，要求限制其低至 8kb。 +因此，扩展属性的大小和数量应保持最小。 + +如果扩展变得流行，那么规范作者可能会考虑将其作为核心属性移入规范。 +这意味着在正式将新属性添加到规范之前，扩展机制/过程可用作审查新属性的一种方式。 + +### JSON 扩展 + +如 [CloudEvents JSON 事件格式](json-format.md)中 +[属性](json-format.md#2-attributes)部分所述， +CloudEvent 扩展属性与已定义属性(必要属性、可选属性)在序列化时处于同一等级 - +也就是说，它们都是 JSON 对象的顶层属性。 +CloudEvent的作者花了很长时间考虑所有选项，并认为这是最好的选择。 +理由如下： + +由于CloudEvents规范遵循 [semver](https://semver.org/) ， +这意味着只要新属性是可选属性，它们可以在核心规范的未来版本定义，而无需更改当前主要版本。 +在这样的情况下，请考虑现有消费者将如何使用新的（未知的）顶级属性。 +虽然消费者可以随意忽略它，因为它是可选的， +但在大多数情况下，这些属性仍然希望向接收这些事件的应用程序公开。 +这可能导致这些应用程序在基础设施不支持的情况下，支持这些属性。 +这意味着未知的顶级属性（无论是谁定义的——规范的未来版本或事件生产者）可能不会被忽略。 +因此，虽然其它一些规范定义了放置扩展的特定属性（例如顶级`extensions`属性）， +但作者认为在传入事件中具有两个不同位置的未知属性可能会导致互操作性问题和开发人员的混淆。 + +扩展属性通常用于测试那些被规范正式采用之前的潜在属性。 +如果有一个`extensions`类型的属性，这个新属性已经被序列化， +那么如果该属性被核心规范采用，它将从`extensions`属性提升（从序列化的角度）为顶级属性。 +如果我们假设这个新属性是可选的，那么当它被核心规范采用时， +它只是一个小版本增量，所有现有的消费者仍然会继续工作。 +但是，消费者将不知道此属性将出现在何处 - 在扩展属性中还是作为顶级属性。 +这意味着他们可能需要同时查看两个地方。 +如果属性出现在两个地方但具有不同的值怎么办？ +生产者是否需要将它放在两个地方，因为他们可能同时有新、老消费者？ +虽然可以为如何解决出现的每个潜在问题而制定明确的规则， +但作者认为一个避免这些问题的更好的办法是在序列化中只有一个位置来放置未知的甚至是新的属性。 +作者还注意到 HTTP 规范现在遵循类似的模式，不再建议扩展 HTTP 头部以 X- 为前缀。 + +## 生产CloudEvents + +CloudEvents 规范有意避免将CloudEvents 的创建方式设计的过于死板。 +例如，它不假定原始事件源必须是该事件生产对应 CloudEvent 的同一实体。 +这允许多种实现方式。 +但是，对于规范的实现者来说，理解规范作者心中的期望还是有帮助的，因为这将有助于确保互操作性和一致性。 + +如上所述，生成初始事件的实体是否与创建相应 CloudEvent 的实体相同是由实现决定的。 +但是，当构建/填充 CloudEvents 属性的实体代表事件源进行操作时，这些属性的值是用来描述事件或事件源， +而不是计算 CloudEvent 属性值的实体的。 +换句话说，当事件源和 CloudEvents 生产者之间的分离对事件使用者没有实质性意义时， +规范定义的属性通常不会包含任何值来指示这种职责分离。 + +这并不是说 CloudEvents 生产者不能向 CloudEvent 添加一些额外的属性， +但这些属性超出了规范的互操作性定义属性的范围。 +这类似于 HTTP 代理通常如何最大限度地减少对传入消息的明确定义的 HTTP 头部的更改， +但它可能会添加一些额外的头部，其中包括一些特定代理的元数据。 + +还值得注意的是，原始事件源和 CloudEvents 生产者之间的这种分离可大可小。 +意思是，即使 CloudEvent 生产者不是原始事件源生态系统的一部分， +如果它代表事件源行事，并且它在事件流中的存在对事件消费者没有意义，那么上述指导仍然适用。 + +当实体同时充当 CloudEvents 的接收者和发送者以转发或转换传入事件时， +出站 CloudEvent 与入站 CloudEvent 匹配的程度将根据该实体的处理语义而有所不同。 +在它充当代理的情况下，它只是将 CloudEvents 转发给另一个事件消费者， +那么出站 CloudEvent 通常看起来与入站 CloudEvent 就规范定义的属性相同 +- 请参阅上一段有关添加其他属性的内容。 + +但是，如果此实体正在执行 CloudEvent 的某种类型的语义处理， +通常会导致`data`属性值发生更改， +则可能需要将其视为与原始事件源不同的“事件源”。 +因此，与事件生产者相关的 CloudEvents 属性（例如`source` and `id`） +将从传入的 CloudEvent 中更改。 + +## 合格的协议与编码 + +正如规范中所表达的，CloudEvents 工作的明确目标是 +“以通用方式描述事件数据”且 +“定义允许服务产生或消费事件的事件系统的互操作性，其中生产者和消费者可以被独立开发和部署”。 + +这种互操作性的基础是开放的数据格式和协议， +CloudEvents 旨在提供这种开放的数据格式，并将其数据格式映射到常用协议和常用编码上。 + +虽然每个软件或服务产品和项目都可以自己选择自己喜欢的通信形式， +但毫无疑问，这种产品或项目私有的专有协议无法进一步实现跨生产者和消费者的广泛互操作性的目标。 + +特别是在消息传递和事件处理领域，该行业在过去十年中开发出了强大且受到广泛支持的协议 +例如 HTTP 1.1 和 HTTP/2 以及 WebSockets 或 Web 上的事件，或者 MQTT 和 AMQP +用于面向连接的消息传递和遥测传输的协议。 + +一些广泛使用的协议已经成为事实上的标准，这些协议来自三个或更多公司的顶级财团打造的强大生态系统， +还有一些来自单个公司发布的强大项目生态系统，在任何一种情况下都与前面提到的标准栈的演变相一致。 + +CloudEvents的努力不应成为认可或推广项目或产品专有协议的工具， +因为这与CloudEvents 的原始目标背道而驰。 + +要使协议或编码符合核心 CloudEvents 事件格式或协议绑定的条件，它必须属于以下任一类别： + +- 该协议具有广泛认可的多供应商协议标准化机构（例如 W3C、IETF、OASIS、ISO）的正式标准地位 +- 该协议在其生态系统类别中具有“事实上的标准”地位， + 这意味着它被广泛使用，甚至被认为是给定应用程序的标准。 + 实际上，我们希望在供应商中立的开源组织（例如 Apache、Eclipse、CNCF、.NET 基金会）的保护伞下 + 看到至少一个开源实现， + 并且至少有十几个独立供应商在他们的产品中使用它的产品或服务。 + +除了正式状态之外，协议或编码是否符合核心 CloudEvents 事件格式或协议绑定的一个关键标准是， +该组织是否认为协议或编码出现后，该规范对与产品或项目无关的任何一方具有持续的实际利益。 +对此的基本要求是协议或编码的定义方式允许独立于产品或项目代码的替代实现。 + +欢迎将 CloudEvents 的所有其他协议和编码格式 +包含在指向相应项目自己的公共仓库，或站点中的 CloudEvents binding信息的列表中。 + +## 专有的协议与编码 + +为了鼓励更多人采用 CloudEvents，本仓库将自动收集专有协议和编码。 +本仓库的维护人员不负责创建、维护或通知专有规范的维护人员有关专有规范和CloudEvents规范间的偏差。 + +专有规范将托管在他们自己的仓库或文档站点中，并记录在[专有规范](proprietary-specs.md) +文件中。 专有规范应遵循与核心协议和编码相关的其他规范相同的格式。 + +专有规范将比核心规范受到更少的审查，并且随着 CloudEvents 规范的发展， +相应协议和编码的维护者有责任使规范与 CloudEvents 规范保持同步。 +如果专有规范过时太多，CloudEvents 可能会将指向该规范的链接标记为已弃用或将其删除。 + +如果为同一个协议创建了多个不兼容的规范，存储库维护者将不知道哪个规范是正确的，并列出所有规范的链接。 + +## 现有技术 + +本节介绍了工作组在 CloudEvent 规范开发过程中使用的一些输入材料。 + +### 角色 + +下面列举了可能涉及事件的产生、管理或消费的各种参与者和场景。 + +在这些中，事件生产者和事件消费者的角色是不同的。 +单个应用程序上下文背景始终可以同时承担多个角色，包括既是事件的生产者又是事件的消费者。 + +1. 应用程序生成供他人使用的事件， + 如为消费者提供有关终端用户活动、状态变化或环境观察的见解， + 或允许通过事件驱动的扩展来补充应用程序的功能。 + + 生产的事件通常与上下文或生产者选择的分类相关。 + 例如，房间中的温度传感器可能被安装位置、房间、楼层和建筑物等上下文限定。 + 运动结果可以按联赛和球队分类。 + + 生产者应用程序可以在任何地方运行，例如在服务器或设备上。 + + 生产的事件可能由生产者或中间人直接提供和发出； + 作为后者的示例，请考虑设备通过负载大小受限的网络（如 LoRaWAN 或 ModBus）传输的事件数据， + 并且符合此规范的事件将由网络网关代表生产者提供。 + + 例如，气象站每 5 分钟通过 LoRaWAN 传输一次 12 字节的专有事件payload用于指示天气状况。 + 然后使用 LoRaWAN 网关以 CloudEvents 格式将事件发布到 Internet 目标。 + LoRaWAN 网关是事件生产者，代表气象站发布事件，并将设置一定的元数据以反映事件的来源(气象站)。 + +2. 应用程序可能以以下目的： + 如显示、存档、分析、工作流处理、监控状态或提供业务解决方案及其基本构建模块的透明化 + 来消费事件。 + + 消费者应用程序可以在任何地方运行，例如在服务器或设备上。 + + 消费应用程序通常对以下内容感兴趣： + + - 区分事件，使得完全相同的事件不会被处理两次。 + - 识别和选择源上下文或生产者指定的分类。 + - 确定事件相对于原始上下文或相对于时钟的时间顺序。 + - 了解事件中携带的上下文相关的详细信息。 + - 关联来自多个事件生产者的事件实例并将它们发送到相同的消费者上下文。 + + 在某些情况下，消费应用程序可能对以下内容感兴趣： + + - 从原始上下文中获取有关事件主题的更多详细信息，例如获取有关需要特权访问授权的已更改对象的详细信息。 + 例如，出于隐私原因，HR 解决方案可能仅在事件中发布非常有限的信息， + 任何需要更多数据的事件消费者都必须在其自己的授权上下文背景下从 HR 系统获取与事件相关的详细信息 + - 在原始上下文中与事件的主题进行交互，例如在被告知该数据块刚刚创建后读取存储该数据块。 + + 消费者的兴趣激发了信息生产者应该包括事件的需求。 + +3. 中间件将事件从生产者路由到消费者，或转发到其他中间件。 + 产生事件的应用程序可能会将根据消费者需求产生的某些任务委托给中间件： + + - 管理同时对大量类别和上下文背景中的某个事件感兴趣的消费者。 + - 代表消费者在类或事件的原始上下文上处理过滤条件。 + - 转码，比如从 JSON 解码后在 MsgPack 中编码。 + - 更改事件结构的转换，例如从专有格式映射到 CloudEvents，同时保留事件的身份和语义完整性。 + - 即时“推送式”传输给感兴趣的消费者。 + - 存储最终传输的事件，用于由消费者发起的“拉”请求，或延迟后由中间件发起“推”请求。 + - 观察事件内容或事件流以进行监控或诊断。 + + 为了满足这些需求，中间件将对以下方面感兴趣： + + - 一种元数据鉴别器，可用于事件的分类或上下文化，以便消费者可以表达对一个或多个类或上下文的兴趣。 + 例如，消费者可能对文件存储帐户内的特定目录相关的所有事件感兴趣。 + - 一种元数据鉴别器，允许区分该类或上下文的特定事件的主题。例如，消费者可能希望过滤掉与以“.jpg”结尾的 + 新文件相关的所有事件（文件名是“新文件”事件的主题），以此表示它对感兴趣的文件存储账户下某个目录的 + 上下文环境。 + - 一个事件及其数据编码的指示器。 + - 一个事件及其数据的结构布局（模式）的指示器。 + + 事件是否可通过中间件消费取决于生产者的选择。 + + 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec_CN.md#生产者)的角色， + 当它根据事件采取行动时可以扮演[消费者](spec_CN.md#消费者)的角色， + 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec_CN.md#中间人)的角色。 + +4. 框架和其他抽象使与事件平台基础设施间的交互更简单， + 并且通常为多个事件平台基础设施提供公共 API 区域。 + + 框架通常用于将事件转换为对象图，并将事件分派给某些特定的处理逻辑或用户规则， + 这些用户逻辑或用户规则允许消费应用程序对原始上下文和特定主题中的特定类型的事件做出反应。 + + 框架最感兴趣的是跨抽象平台的语义元数据通用性，以便可以统一处理类似的活动。 + + 对于体育应用程序，使用该框架的开发人员可能对联盟中一支球队今天的比赛（主题） + 的所有事件感兴趣，但希望以不同于“换人”事件的方式处理“得分”事件。 + 为此，框架将需要一个合适的元数据鉴别器，使其不必了解事件细节。 + +### 价值主张 + +本节介绍了一些能够展示 CloudEvents 价值主张的用例。 + +#### 跨服务和平台规范化事件 + +主要事件发布者（例如 AWS、Microsoft、Google 等）都在各自的平台上以不同的格式发布事件。 +甚至在少数情况下，同一提供商的服务以不同格式（例如 AWS）发布事件。 +这迫使事件消费者实现自定义逻辑以跨平台读取或处理事件数据，有时甚至需要跨单个平台的多个服务处理。 + +CloudEvents 可以为那些跨平台和服务处理事件的使用者提供单一体验。 + +#### 促进跨服务和平台的集成 + +跨环境传输的事件数据越来越普遍。 +然而，如果没有描述事件的通用方式，跨环境的事件传递就会受到阻碍。 +CloudEvents之前没有单一的方法可以确定事件的来源和可能的去向。 +这对研究成功传输事件事件工具和消费者知道如何处理事件数据形成了巨大阻碍。 + +CloudEvents 提供有用的元数据，中间件和消费者可以依赖这些元数据来促进事件路由、日志记录、传输和接收。 + +#### 提高功能即服务的可移植性 + +功能即服务（也称为serverless计算）是 IT 中增长最快的趋势之一，它主要是由事件驱动的。 +然而，FaaS 的一个主要问题是供应商锁定。 +这种锁定部分是由函数 API 和供应商之间签名的差异引起的， +锁定同样也是由函数内接收的事件数据格式的差异引起的。 + +CloudEvents提供描述事件数据的通用方式提高了功能即服务的可移植性。 + +#### 改进事件驱动/serverless架构的开发和测试 + +缺乏通用事件格式使事件驱动和serverless架构的开发和测试变得复杂。 +没有简单的方法可以准确地为开发和测试目的模拟事件，并帮助在开发环境中模拟事件驱动的工作流。 + +CloudEvents 可以提供更好的开发工具来构建、测试和处理事件驱动和无服务器架构的端到端生命周期。 + +#### 事件数据发展 + +大多数平台和服务对其事件的数据模型进行不同的版本控制（如果他们这样做的话）。 +随着这些数据模型的发展，这会为发布和使用事件的数据模型带来不一致的体验。 + +CloudEvents 可以提供一种通用的方式来版本化和演化事件数据的发展。 +这将帮助事件发布者根据最佳实践安全地对其数据模型进行版本控制， +并且这有助于事件消费者随着事件数据的发展安全地使用它。 + +#### 规范化 Webhook + +Webhooks 是一种不使用通用格式的来发布事件的模式。 +Webhook 的使用者没有一致的方式来开发、测试、识别、验证和整体处理通过 Webhook 传输的事件数据。 + +CloudEvents 可以提供 Webhook 发布和消费事件的一致性。 + +#### 安全策略 + +出于安全和策略考虑，可能需要过滤、转换或阻止系统之间的事件传输。 +比如可能需要防止事件的进入或退出，如包含敏感信息的事件数据或想要禁止发送方和接收方之间的信息流。 + +通用事件格式将允许更容易地推理正在传输的数据，并提供更好的数据自查。 + +#### 事件追踪 + +从源发送的事件可能会出现在一系列附加事件序列之中， +这些附加事件序列从各种中间件设备（例如事件代理和网关）发出。 +CloudEvents 在事件中包含元数据以将这些事件关联为事件序列的一部分，以便进行事件跟踪和故障排除。 + +#### IoT + +物联网设备会发送和接收与其功能相关的事件。 +例如，连接的恒温器将发送有关当前温度的遥测数据， +并可以接收改变温度的事件。 +这些设备通常具有受限的操作环境（cpu、内存），需要明确定义的事件消息格式。 +在很多情况下，这些消息是二进制编码的，而不是文本的。 +无论是直接来自设备还是通过网关转换，CloudEvents 都可以更好地描述消息的来源和消息中包含的数据格式。 + +#### 事件关联 + +一个serverless应用或工作流可能与来自不同事件源或事件生产者的多个事件相关联。 +例如，盗窃检测应用程序/工作流可能涉及运动事件和门/窗打开事件。 +一个serverless平台可能接收每种类型事件的许多实例，例如 它可以接收来自不同房屋的运动事件和开窗事件。 + +serverless平台需要将一种类型的事件实例与其他类型的事件实例正确关联， +并将接收到的事件实例映射到正确的应用/工作流实例。 +CloudEvents 将为任何事件使用者（例如serverless平台）提供一种标准方式， +以在事件数据中定位事件关联信息/令牌并将接收到的事件实例映射到正确的应用/工作流实例。 + +### 现有的数据格式 + +与上一节一样，对当前现状的调查（和理解）对CloudEvents 小组来说非常重要。 +为此，下面列出了在实践中被广泛使用的当前事件格式的样本。 + +#### Microsoft - Event Grid + +``` +{ + "topic":"/subscriptions/{subscription-id}", + "subject":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/eventSubscriptions/LogicAppdd584bdf-8347-49c9-b9a9-d1f980783501", + "eventType":"Microsoft.Resources.ResourceWriteSuccess", + "eventTime":"2017-08-16T03:54:38.2696833Z", + "id":"25b3b0d0-d79b-44d5-9963-440d4e6a9bba", + "data": { + "authorization":"{azure_resource_manager_authorizations}", + "claims":"{azure_resource_manager_claims}", + "correlationId":"54ef1e39-6a82-44b3-abc1-bdeb6ce4d3c6", + "httpRequest":"", + "resourceProvider":"Microsoft.EventGrid", + "resourceUri":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/eventSubscriptions/LogicAppdd584bdf-8347-49c9-b9a9-d1f980783501", + "operationName":"Microsoft.EventGrid/eventSubscriptions/write", + "status":"Succeeded", + "subscriptionId":"{subscription-id}", + "tenantId":"72f988bf-86f1-41af-91ab-2d7cd011db47" + } +} +``` + +[Documentation](https://docs.microsoft.com/en-us/azure/event-grid/event-schema) + +#### Google - Cloud Functions (potential future) + +``` +{ + "data": { + "@type": "types.googleapis.com/google.pubsub.v1.PubsubMessage", + "attributes": { + "foo": "bar", + }, + "messageId": "12345", + "publishTime": "2017-06-05T12:00:00.000Z", + "data": "somebase64encodedmessage" + }, + "context": { + "eventId": "12345", + "timestamp": "2017-06-05T12:00:00.000Z", + "eventTypeId": "google.pubsub.topic.publish", + "resource": { + "name": "projects/myProject/topics/myTopic", + "service": "pubsub.googleapis.com" + } + } +} +``` + +#### AWS - CloudWatch Events + +AWS 上的很大一部分事件处理系统都在使用这种格式。 + +``` +{ + "version": "0", + "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718", + "detail-type": "EC2 Instance State-change Notification", + "source": "aws.ec2", + "account": "111122223333", + "time": "2017-12-22T18:43:48Z", + "region": "us-west-1", + "resources": [ + "arn:aws:ec2:us-west-1:123456789012:instance/i-1234567890abcdef0" + ], + "detail": { + "instance-id": "i-1234567890abcdef0", + "state": "terminated" + } +} +``` + +#### IBM - OpenWhisk - Web Action Event + +``` +{ + "__ow_method": "post", + "__ow_headers": { + "accept": "*/*", + "connection": "close", + "content-length": "4", + "content-type": "text/plain", + "host": "172.17.0.1", + "user-agent": "curl/7.43.0" + }, + "__ow_path": "", + "__ow_body": "Jane" +} +``` + +#### OpenStack - Audit Middleware - Event + +``` +{ + "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", + "id": "d8304637-3f63-5092-9ab3-18c9781871a2", + "eventTime": "2018-01-30T10:46:16.740253+00:00", + "action": "delete", + "eventType": "activity", + "outcome": "success", + "reason": { + "reasonType": "HTTP", + "reasonCode": "204" + }, + "initiator": { + "typeURI": "service/security/account/user", + "name": "user1", + "domain": "domain1", + "id": "52d28347f0b4cf9cc1717c00adf41c74cc764fe440b47aacb8404670a7cd5d22", + "host": { + "address": "127.0.0.1", + "agent": "python-novaclient" + }, + "project_id": "ae63ddf2076d4342a56eb049e37a7621" + }, + "target": { + "typeURI": "compute/server", + "id": "b1b475fc-ef0a-4899-87f3-674ac0d56855" + }, + "observer": { + "typeURI": "service/compute", + "name": "nova", + "id": "1b5dbef1-c2e8-5614-888d-bb56bcf65749" + }, + "requestPath": "/v2/ae63ddf2076d4342a56eb049e37a7621/servers/b1b475fc-ef0a-4899-87f3-674ac0d56855" +} +``` + +[Documentation](https://github.com/openstack/pycadf/blob/master/doc/source/event_concept.rst) + +#### Adobe - I/O Events + +``` +{ + "event_id": "639fd17a-d0bb-40ca-83a4-e78612bce5dc", + "event": { + "@id": "82235bac-2b81-4e70-90b5-2bd1f04b5c7b", + "@type": "xdmCreated", + "xdmEventEnvelope:objectType": "xdmAsset", + "activitystreams:to": { + "xdmImsUser:id": "D13A1E7053E46A220A4C86E1@AdobeID", + "@type": "xdmImsUser" + }, + "activitystreams:generator": { + "xdmContentRepository:root": "https://cc-api-storage.adobe.io/", + "@type": "xdmContentRepository" + }, + "activitystreams:actor": { + "xdmImsUser:id": "D13A1E7053E46A220A4C86E1@AdobeID", + "@type": "xdmImsUser" + }, + "activitystreams:object": { + "@type": "xdmAsset", + "xdmAsset:asset_id": "urn:aaid:sc:us:4123ba4c-93a8-4c5d-b979-ffbbe4318185", + "xdmAsset:asset_name": "example.jpg", + "xdmAsset:etag": "6fc55d0389d856ae7deccebba54f110e", + "xdmAsset:path": "/MyFolder/example.jpg", + "xdmAsset:format": "image/jpeg" + }, + "activitystreams:published": "2016-07-16T19:20:30+01:00" + } +} +``` + +[Documentation](https://www.adobe.io/apis/cloudplatform/events/documentation.html) From 1c830b268dec362188cee638d812c3855b5e8e86 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:54:13 +0800 Subject: [PATCH 58/60] Delete primer_CN.md Signed-off-by: JieDing --- primer_CN.md | 704 --------------------------------------------------- 1 file changed, 704 deletions(-) delete mode 100644 primer_CN.md diff --git a/primer_CN.md b/primer_CN.md deleted file mode 100644 index 5b5b77bc6..000000000 --- a/primer_CN.md +++ /dev/null @@ -1,704 +0,0 @@ -# CloudEvents 入门文档 - 1.0 版本 - -Declaration： This manual aims to provide a fast and brief introduction of CloudEvents -in Chinese for people who are new to CloudEvents. -Most of the content is translated from the original English version. -It is strongly recommended to read the English version if you find anything lost in translation. - -## 摘要 - -这份非技术规范文档用来为你提供关于CloudEvents规范的总体概览。它补充了CloudEvents规范的相关背景 -以及在制定 本规范时的历史和设计理念。这样，CloudEvents的核心规范就只需要关注Events规范的技术细节， -而不用过多地关心背景相关内容。 - -## 目录 - -- [历史](#历史) -- [CloudEvents 概念](#CloudEvents-概念) -- [设计目标](#设计目标) -- [架构](#架构) -- [属性版本控制](#属性版本控制) -- [CloudEvent 属性](#CloudEvent-属性) -- [CloudEvent 属性扩展](#CloudEvent-属性扩展) -- [生产 CloudEvents](#生产CloudEvents) -- [合格的协议与编码](#合格的协议与编码) -- [专有的协议和编码](#专有的协议与编码) -- [现有技术](#现有技术) -- [角色](#角色) -- [价值主张](#价值主张) -- [现有的数据格式](#现有的数据格式) - -## 历史 - -[CNCF Serverless 工作组](https://github.com/cncf/wg-serverless) 是由 CNCF的 -[技术监管委员会](https://github.com/cncf/toc) 成立，用于研究 -Serverless相关技术并为CNCF推荐相关领域的未来发展计划的。工作组其中一项建议就是研究创建一种通用事件格式， -用于提升不同云厂商间函数的可移植性和事件流处理的互操作性。就此，CloudEvents应运而生。 - -尽管CloudEvents起初是作为Serverless工作组的项目进行的，但随着CloudEvents规范完成它v0.1版本的里程碑， -技术监管委员会批准了CloudEvents作为一个新的独立的CNCF沙箱级项目。 - -## CloudEvents-概念 - -一个[事件](spec_CN.md#事件)包含了[事件发生](spec_CN.md#发生)的上下文和相关数据。 -事件的相关数据可以用来唯一标识一件事件的发生。 - -事件代表了已发生的事实，因此它并不包含任何目的地相关信息，但消息能够传达事件内容，从而将事件数据 -从源头传输到指定的目的地。 - -### 事件使用 - -事件通常在服务器端代码中使用来连接不同的系统，其中一个系统中的状态变化会导致代码在另一个系统中执行。 -比如，一个事件源，可能会在收到某个外部信号(如HTTP或RPC)或观察到状态变化(如IoT传感器数据变化或不活跃) -时，生产一个事件。 - -为了更好地解释一个系统如何使用CloudEvents，下图展示了一个从事件源生产的事件是如何触发一个行为的。 - -![alt text](source-event-action.png "A box representing the source with -arrow pointing to a box representing the action. The arrow is annotated with -'e' for event and 'protocol'.") - -事件源生产了一条封装了基于某种协议的事件数据的消息。 -当载有事件的消息到达目的地时，会触发一个使用了事件数据的行为函数。 - -一个事件源是那些允许暂存和测试实例的源类型的特定实例。 -某个特定源类型的开源软件可能由多个公司或提供商部署。 - -事件可以通过各种行业标准协议（如HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或 -平台/供应商专有协议（AWS Kinesis、Azure Event Grid）传输。 - -一个操作函数能够处理那些定义了行为或影响的事件，这些行为和效果由来自特定源的特定事件触发而来。 -虽然超出了规范的范围，但生成事件的目的通常是让其他系统能够轻松地对它们无法控制的源中的更改做出反应。 -源和操作通常由不同的开发人员构建。 -通常，源是托管服务，而操作是serverless函数（如 AWS Lambda 或 Google Cloud Functions）中 -的自定义代码。 - -## 设计目标 - -CloudEvents 通常用于分布式系统，以允许服务在开发过程中松耦合，独立部署，方便之后连接以创建新的应用程序。 - -CloudEvents 规范的目标是定义允许服务生产或消费事件的事件系统的互操作性， -其中生产者和消费者可以独立开发和部署。 生产者可以在没有消费者监听时就生成事件， -消费者也可以表达对尚未生成的事件或事件类的兴趣。值得注意的是，这项工作产生的规范侧重于事件格式的互操作性 -以及它在通过各种协议（例如 HTTP）发送时的显示方式。我们不关注事件生产者或事件消费者的处理模型。 - -CloudEvents的核心规范中定义了一组称之为属性的元数据， -它们描述了在系统之间传输的事件以及这些元数据片段应如何显示在该消息中。 -这些元数据是，将请求路由到适当组件并帮助该组件正确处理事件所需的最小信息集。 -因此，某些事件本身的数据可能会作为 CloudEvent 属性集的一部分而被复制， -但这样做仅是为了能够正确传递和处理消息。那些不用于该目的的数据应放置在事件（数据）本身中。 - -此外，本规范中假设协议层所需的用来将消息传递到目标系统的元数据应完全由协议处理， -因此不包含在 CloudEvents 属性中。 有关更多详细信息，请参阅[非目标](#非目标)部分。 - -除了这些属性的定义之外，规范还描述了关于如何序列化 -不同格式（例如 JSON）和协议（例如 HTTP、AMQP、Kafka）的事件。 - -一些协议本身支持将多个事件批处理到单个 API 的调用中。 -为了提升系统间的互操作性，是否以及如何实现批处理将由协议自己决定。 -相关详细信息可以在协议绑定或协议规范中找到。 -成批的CloudEvents并没有语义，也没有排序。 -[中间人](spec_CN.md#中间人)可以添加或删除批处理以及将事件分配给不同的批处理。 - -### 非目标 - -以下内容不在本规范的范围之内： - -- 函数的构建和调用过程 -- 特定语言的运行时 APIs -- 选择单一身份认证或访问控制的系统 -- 包含协议级路由信息 -- 事件持久化过程 - -就连那些刚接触 CloudEvents 概念的人都会建议 -CloudEvents 规范不应包括协议级路由信息（例如，将事件发送到的目标的URL）。 -经过深思熟虑，工作组得出的结论是，CloudEvents规范中不需要路由信息： -因为任何现有的协议（例如 HTTP、MQTT、XMPP 或 Pub/Sub 总线）都已经定义了路由语义。 -例如，CloudEvents [HTTP 绑定](http-protocol-binding.md) 规定了头部和请求正文内容。 -CloudEvents 不需要在规范中包含目标 URL 即可与 HTTP 兼容；HTTP 规范已经在 -[请求行](https://tools.ietf.org/html/rfc2616#section-5.1) 中包含了所需的目标URL。 - -路由信息不仅是多余的，而且是有害的。 -CloudEvents 应该增加互操作性并解耦事件的生产者和消费者。 -禁止来自事件格式的路由信息允许将 CloudEvents 重新传送到新的行为，或通过包含多个通道的复杂中继传送。 -例如，如果 Webhook 地址不可用，则用于 Webhook 的 CloudEvent 应可传送到死信队列。 -死信队列应该能够将事件传送给原始事件发射者从未想象过的新的行为上。 - -在系统内和跨系统生产和消费的 CloudEvent能够触发产生价值的行为。 -因此，对于调试或复制的目的而言，存档和或重放事件可能很有价值。 -但是，持久化事件会删除传输期间可用的上下文信息，例如生产者的身份和权利、保真验证机制或机密性保护。 -此外，持久化会增加满足用户需求的复杂性和挑战。 -例如，出于加密或签名目的重复使用私钥会增加攻击者可用的信息，从而降低安全性。 -因此我们推测，可以定义有助于满足持久性要求的属性，但这些属性可能随着行业最佳实践和进步而不断发展。 - -## 架构 -CloudEvents 规范集定义了四种有助于形成分层架构模型的不同类型的协议元素。 -基本规范定义了一个抽象信息模型，该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 - -1. [基本规范](spec_CN.md) 定义了一个抽象信息模型， - 该模型由属性（键值对）和构成 CloudEvent 的相关规则组成。 -2. [扩展属性](./spec_CN.md#扩展上下文属性) - 添加了特定于用例且可能重叠的扩展属性集和相关规则，如支持不同的追踪标准的规则。 -3. 事件格式编码,如 [JSON](json-format.md), 定义了基本规范的信息模型与所选扩展的编码方式， - 以将其映射到应用程序协议的头部和负载元素。 -4. 协议绑定, 如. [HTTP协议绑定](http-protocol-binding.md), - 在HTTP to HTTP的情况下， - 定义了 CloudEvent 如何绑定到应用程序协议的传输层 。 - 协议绑定不限制传输层的使用方式，这意味着 HTTP绑定可用于任何 HTTP方法以及请求和响应消息。 - -为了确保更广泛的互操作性，CloudEvents规范集为使用专有应用协议的事件传输提供了特定约束。 -[HTTP Webhook](http-webhook.md)规范并非特定于 CloudEvents， -而是可用于将任何类型的单向事件和通知发布到符合标准的 HTTP 端点。 -但是，由于其他地方缺乏此类规范，因此 CloudEvents 需要对其进行定义。 - -### 协议错误处理 - -CloudEvents 规范在很大程度上并未规定与 CloudEvents 的创建或处理相关联的处理模型。 -因此，如果在处理 CloudEvent 过程中出现错误， -请使用正常的协议级错误处理机制进行处理。 - -## 属性版本控制 - -对于某些 CloudEvents 属性，由其值引用的实体或数据模型可能会随时间变化。 -例如，`dataschema`可能引用模式文档的一个特定版本。 -通常，这些属性值会通过将一些特定于版本的字符串作为其值的一部分来区分每个变体。 -例如，可能会加入版本号 (v1, v2) 或日期 (2018-01-01)来区分。 - -CloudEvents 规范不强制要求使用任何特定模式，甚至根本不强制使用版本字符串。 -是否使用完全取决于每个事件生产者。 -但是，当使用特定版本的字符串时，每当其值发生变化时都应注意， -因为事件消费者可能依赖于现有值，因此更改可能被解释为“破坏性更改”。 -应该在生产者和消费者之间建立某种形式的通信，以确保事件消费者知道能使用哪些可能的值。 -通常，这也适用于所有 CloudEvents 属性。 - -## CloudEvent-属性 - -本节介绍了与CloudEvent 属性相关的其他背景和设计要点。 - -### id - -`id` 属性是一个在同一事件源下所有事件中用来标识事件唯一的值 -（其中每个事件源由其 CloudEvents `source`属性唯一标识）。 -虽然`id`使用的确切值是生产者定义的， -但必须要确保来自单个事件源的 CloudEvents 消费者不会有两个事件共享相同的 id 值。 -唯一的例外是如果支持事件的重播，在这些情况下，可以使用 id 来检测这一点。 - -由于一次事件的发生可能导致生成多个cloud event， -在所有这些事件都来自同一事件源的情况下， -生成的每个 CloudEvent 将具有唯一的 `id`。 -以创建数据库条目为例，这一事件的发生可能会生成一个类型为 create 的 CloudEvent -和一个类型为 write 的 CloudEvent。 -这两个 CloudEvents 各自都有一个唯一的 ID。 -如果需要在这两个 CloudEvent 之间建立某种关联以表明它们都与同一事件相关， -那么可以使用 CloudEvent 中的一些附加数据来实现该目的。 - -从这方面来看，虽然事件生产者对`id`的使用可能是某个随机字符串， -或者在其它上下文中具有某种语义的字符串， -但对于此 CloudEvent 属性而言，这些含义并不成立， -因此本规范不建议将 `id` 用于除了唯一性检查之外的其它目的。 - -## CloudEvent-属性扩展 - -为了实现规范的设计目标， -规范作者将尝试限制他们在 CloudEvents 中定义的元数据属性的数量。 -为此，该项目定义的属性将分为以下三类： - -- 必要属性 -- 可选属性 -- 扩展属性 - -正如类别名称所暗示的那样， -“必要”属性是工作组认为在任何情况下，对所有事件都至关重要的属性， -而“可选”属性将在大多数情况下使用。 这些情况下的两个属性都在本规范中定义了出来。 - -工作组考虑到某些属性不够常见而不能归入上述两个类别， -但此类属性的良好定义仍会使系统间的互操作性级别受益， -因此将这些属性放入了“扩展”类别并记录在[扩展文档](documented-extensions.md)中， -本规范定义了这些扩展属性在 CloudEvent 中的显示方式。 - -在确定提议的属性属于哪个类别时， -工作组使用现有的用例和用户故事来解释它们的基本原理和需求。 -相关信息将添加到本文档的[现有技术](#现有技术)部分。 - -CloudEvent 规范的扩展属性是需要包含的附加元数据，它们能确保正确的路由和正确处理CloudEvent。 -用于其它目的的附加元数据， -即那些与事件本身相但在 CloudEvent 的传输或处理中不需要的元数据， -应改为放置在事件 (`data`)的扩展点内。 - -扩展属性应保持最少，以确保 CloudEvent 可以正确序列化和传输。 -事件生产者应该考虑在向 CloudEvent 添加扩展时可能遇到的技术限制。 -例如，[HTTP Binary Mode](http-protocol-binding.md#31-binary-content-mode) -使用 HTTP 头来传输元数据； -大多数 HTTP 服务器会拒绝包含过多 HTTP 头部数据的请求，要求限制其低至 8kb。 -因此，扩展属性的大小和数量应保持最小。 - -如果扩展变得流行，那么规范作者可能会考虑将其作为核心属性移入规范。 -这意味着在正式将新属性添加到规范之前，扩展机制/过程可用作审查新属性的一种方式。 - -### JSON 扩展 - -如 [CloudEvents JSON 事件格式](json-format.md)中 -[属性](json-format.md#2-attributes)部分所述， -CloudEvent 扩展属性与已定义属性(必要属性、可选属性)在序列化时处于同一等级 - -也就是说，它们都是 JSON 对象的顶层属性。 -CloudEvent的作者花了很长时间考虑所有选项，并认为这是最好的选择。 -理由如下： - -由于CloudEvents规范遵循 [semver](https://semver.org/) ， -这意味着只要新属性是可选属性，它们可以在核心规范的未来版本定义，而无需更改当前主要版本。 -在这样的情况下，请考虑现有消费者将如何使用新的（未知的）顶级属性。 -虽然消费者可以随意忽略它，因为它是可选的， -但在大多数情况下，这些属性仍然希望向接收这些事件的应用程序公开。 -这可能导致这些应用程序在基础设施不支持的情况下，支持这些属性。 -这意味着未知的顶级属性（无论是谁定义的——规范的未来版本或事件生产者）可能不会被忽略。 -因此，虽然其它一些规范定义了放置扩展的特定属性（例如顶级`extensions`属性）， -但作者认为在传入事件中具有两个不同位置的未知属性可能会导致互操作性问题和开发人员的混淆。 - -扩展属性通常用于测试那些被规范正式采用之前的潜在属性。 -如果有一个`extensions`类型的属性，这个新属性已经被序列化， -那么如果该属性被核心规范采用，它将从`extensions`属性提升（从序列化的角度）为顶级属性。 -如果我们假设这个新属性是可选的，那么当它被核心规范采用时， -它只是一个小版本增量，所有现有的消费者仍然会继续工作。 -但是，消费者将不知道此属性将出现在何处 - 在扩展属性中还是作为顶级属性。 -这意味着他们可能需要同时查看两个地方。 -如果属性出现在两个地方但具有不同的值怎么办？ -生产者是否需要将它放在两个地方，因为他们可能同时有新、老消费者？ -虽然可以为如何解决出现的每个潜在问题而制定明确的规则， -但作者认为一个避免这些问题的更好的办法是在序列化中只有一个位置来放置未知的甚至是新的属性。 -作者还注意到 HTTP 规范现在遵循类似的模式，不再建议扩展 HTTP 头部以 X- 为前缀。 - -## 生产CloudEvents - -CloudEvents 规范有意避免将CloudEvents 的创建方式设计的过于死板。 -例如，它不假定原始事件源必须是该事件生产对应 CloudEvent 的同一实体。 -这允许多种实现方式。 -但是，对于规范的实现者来说，理解规范作者心中的期望还是有帮助的，因为这将有助于确保互操作性和一致性。 - -如上所述，生成初始事件的实体是否与创建相应 CloudEvent 的实体相同是由实现决定的。 -但是，当构建/填充 CloudEvents 属性的实体代表事件源进行操作时，这些属性的值是用来描述事件或事件源， -而不是计算 CloudEvent 属性值的实体的。 -换句话说，当事件源和 CloudEvents 生产者之间的分离对事件使用者没有实质性意义时， -规范定义的属性通常不会包含任何值来指示这种职责分离。 - -这并不是说 CloudEvents 生产者不能向 CloudEvent 添加一些额外的属性， -但这些属性超出了规范的互操作性定义属性的范围。 -这类似于 HTTP 代理通常如何最大限度地减少对传入消息的明确定义的 HTTP 头部的更改， -但它可能会添加一些额外的头部，其中包括一些特定代理的元数据。 - -还值得注意的是，原始事件源和 CloudEvents 生产者之间的这种分离可大可小。 -意思是，即使 CloudEvent 生产者不是原始事件源生态系统的一部分， -如果它代表事件源行事，并且它在事件流中的存在对事件消费者没有意义，那么上述指导仍然适用。 - -当实体同时充当 CloudEvents 的接收者和发送者以转发或转换传入事件时， -出站 CloudEvent 与入站 CloudEvent 匹配的程度将根据该实体的处理语义而有所不同。 -在它充当代理的情况下，它只是将 CloudEvents 转发给另一个事件消费者， -那么出站 CloudEvent 通常看起来与入站 CloudEvent 就规范定义的属性相同 -- 请参阅上一段有关添加其他属性的内容。 - -但是，如果此实体正在执行 CloudEvent 的某种类型的语义处理， -通常会导致`data`属性值发生更改， -则可能需要将其视为与原始事件源不同的“事件源”。 -因此，与事件生产者相关的 CloudEvents 属性（例如`source` and `id`） -将从传入的 CloudEvent 中更改。 - -## 合格的协议与编码 - -正如规范中所表达的，CloudEvents 工作的明确目标是 -“以通用方式描述事件数据”且 -“定义允许服务产生或消费事件的事件系统的互操作性，其中生产者和消费者可以被独立开发和部署”。 - -这种互操作性的基础是开放的数据格式和协议， -CloudEvents 旨在提供这种开放的数据格式，并将其数据格式映射到常用协议和常用编码上。 - -虽然每个软件或服务产品和项目都可以自己选择自己喜欢的通信形式， -但毫无疑问，这种产品或项目私有的专有协议无法进一步实现跨生产者和消费者的广泛互操作性的目标。 - -特别是在消息传递和事件处理领域，该行业在过去十年中开发出了强大且受到广泛支持的协议 -例如 HTTP 1.1 和 HTTP/2 以及 WebSockets 或 Web 上的事件，或者 MQTT 和 AMQP -用于面向连接的消息传递和遥测传输的协议。 - -一些广泛使用的协议已经成为事实上的标准，这些协议来自三个或更多公司的顶级财团打造的强大生态系统， -还有一些来自单个公司发布的强大项目生态系统，在任何一种情况下都与前面提到的标准栈的演变相一致。 - -CloudEvents的努力不应成为认可或推广项目或产品专有协议的工具， -因为这与CloudEvents 的原始目标背道而驰。 - -要使协议或编码符合核心 CloudEvents 事件格式或协议绑定的条件，它必须属于以下任一类别： - -- 该协议具有广泛认可的多供应商协议标准化机构（例如 W3C、IETF、OASIS、ISO）的正式标准地位 -- 该协议在其生态系统类别中具有“事实上的标准”地位， - 这意味着它被广泛使用，甚至被认为是给定应用程序的标准。 - 实际上，我们希望在供应商中立的开源组织（例如 Apache、Eclipse、CNCF、.NET 基金会）的保护伞下 - 看到至少一个开源实现， - 并且至少有十几个独立供应商在他们的产品中使用它的产品或服务。 - -除了正式状态之外，协议或编码是否符合核心 CloudEvents 事件格式或协议绑定的一个关键标准是， -该组织是否认为协议或编码出现后，该规范对与产品或项目无关的任何一方具有持续的实际利益。 -对此的基本要求是协议或编码的定义方式允许独立于产品或项目代码的替代实现。 - -欢迎将 CloudEvents 的所有其他协议和编码格式 -包含在指向相应项目自己的公共仓库，或站点中的 CloudEvents binding信息的列表中。 - -## 专有的协议与编码 - -为了鼓励更多人采用 CloudEvents，本仓库将自动收集专有协议和编码。 -本仓库的维护人员不负责创建、维护或通知专有规范的维护人员有关专有规范和CloudEvents规范间的偏差。 - -专有规范将托管在他们自己的仓库或文档站点中，并记录在[专有规范](proprietary-specs.md) -文件中。 专有规范应遵循与核心协议和编码相关的其他规范相同的格式。 - -专有规范将比核心规范受到更少的审查，并且随着 CloudEvents 规范的发展， -相应协议和编码的维护者有责任使规范与 CloudEvents 规范保持同步。 -如果专有规范过时太多，CloudEvents 可能会将指向该规范的链接标记为已弃用或将其删除。 - -如果为同一个协议创建了多个不兼容的规范，存储库维护者将不知道哪个规范是正确的，并列出所有规范的链接。 - -## 现有技术 - -本节介绍了工作组在 CloudEvent 规范开发过程中使用的一些输入材料。 - -### 角色 - -下面列举了可能涉及事件的产生、管理或消费的各种参与者和场景。 - -在这些中，事件生产者和事件消费者的角色是不同的。 -单个应用程序上下文背景始终可以同时承担多个角色，包括既是事件的生产者又是事件的消费者。 - -1. 应用程序生成供他人使用的事件， - 如为消费者提供有关终端用户活动、状态变化或环境观察的见解， - 或允许通过事件驱动的扩展来补充应用程序的功能。 - - 生产的事件通常与上下文或生产者选择的分类相关。 - 例如，房间中的温度传感器可能被安装位置、房间、楼层和建筑物等上下文限定。 - 运动结果可以按联赛和球队分类。 - - 生产者应用程序可以在任何地方运行，例如在服务器或设备上。 - - 生产的事件可能由生产者或中间人直接提供和发出； - 作为后者的示例，请考虑设备通过负载大小受限的网络（如 LoRaWAN 或 ModBus）传输的事件数据， - 并且符合此规范的事件将由网络网关代表生产者提供。 - - 例如，气象站每 5 分钟通过 LoRaWAN 传输一次 12 字节的专有事件payload用于指示天气状况。 - 然后使用 LoRaWAN 网关以 CloudEvents 格式将事件发布到 Internet 目标。 - LoRaWAN 网关是事件生产者，代表气象站发布事件，并将设置一定的元数据以反映事件的来源(气象站)。 - -2. 应用程序可能以以下目的： - 如显示、存档、分析、工作流处理、监控状态或提供业务解决方案及其基本构建模块的透明化 - 来消费事件。 - - 消费者应用程序可以在任何地方运行，例如在服务器或设备上。 - - 消费应用程序通常对以下内容感兴趣： - - - 区分事件，使得完全相同的事件不会被处理两次。 - - 识别和选择源上下文或生产者指定的分类。 - - 确定事件相对于原始上下文或相对于时钟的时间顺序。 - - 了解事件中携带的上下文相关的详细信息。 - - 关联来自多个事件生产者的事件实例并将它们发送到相同的消费者上下文。 - - 在某些情况下，消费应用程序可能对以下内容感兴趣： - - - 从原始上下文中获取有关事件主题的更多详细信息，例如获取有关需要特权访问授权的已更改对象的详细信息。 - 例如，出于隐私原因，HR 解决方案可能仅在事件中发布非常有限的信息， - 任何需要更多数据的事件消费者都必须在其自己的授权上下文背景下从 HR 系统获取与事件相关的详细信息 - - 在原始上下文中与事件的主题进行交互，例如在被告知该数据块刚刚创建后读取存储该数据块。 - - 消费者的兴趣激发了信息生产者应该包括事件的需求。 - -3. 中间件将事件从生产者路由到消费者，或转发到其他中间件。 - 产生事件的应用程序可能会将根据消费者需求产生的某些任务委托给中间件： - - - 管理同时对大量类别和上下文背景中的某个事件感兴趣的消费者。 - - 代表消费者在类或事件的原始上下文上处理过滤条件。 - - 转码，比如从 JSON 解码后在 MsgPack 中编码。 - - 更改事件结构的转换，例如从专有格式映射到 CloudEvents，同时保留事件的身份和语义完整性。 - - 即时“推送式”传输给感兴趣的消费者。 - - 存储最终传输的事件，用于由消费者发起的“拉”请求，或延迟后由中间件发起“推”请求。 - - 观察事件内容或事件流以进行监控或诊断。 - - 为了满足这些需求，中间件将对以下方面感兴趣： - - - 一种元数据鉴别器，可用于事件的分类或上下文化，以便消费者可以表达对一个或多个类或上下文的兴趣。 - 例如，消费者可能对文件存储帐户内的特定目录相关的所有事件感兴趣。 - - 一种元数据鉴别器，允许区分该类或上下文的特定事件的主题。例如，消费者可能希望过滤掉与以“.jpg”结尾的 - 新文件相关的所有事件（文件名是“新文件”事件的主题），以此表示它对感兴趣的文件存储账户下某个目录的 - 上下文环境。 - - 一个事件及其数据编码的指示器。 - - 一个事件及其数据的结构布局（模式）的指示器。 - - 事件是否可通过中间件消费取决于生产者的选择。 - - 在实践中，当中间件改变事件的语义时可以扮演[生产者](spec_CN.md#生产者)的角色， - 当它根据事件采取行动时可以扮演[消费者](spec_CN.md#消费者)的角色， - 或者当它路由事件而不进行语义改变时可以扮演[中间人](spec_CN.md#中间人)的角色。 - -4. 框架和其他抽象使与事件平台基础设施间的交互更简单， - 并且通常为多个事件平台基础设施提供公共 API 区域。 - - 框架通常用于将事件转换为对象图，并将事件分派给某些特定的处理逻辑或用户规则， - 这些用户逻辑或用户规则允许消费应用程序对原始上下文和特定主题中的特定类型的事件做出反应。 - - 框架最感兴趣的是跨抽象平台的语义元数据通用性，以便可以统一处理类似的活动。 - - 对于体育应用程序，使用该框架的开发人员可能对联盟中一支球队今天的比赛（主题） - 的所有事件感兴趣，但希望以不同于“换人”事件的方式处理“得分”事件。 - 为此，框架将需要一个合适的元数据鉴别器，使其不必了解事件细节。 - -### 价值主张 - -本节介绍了一些能够展示 CloudEvents 价值主张的用例。 - -#### 跨服务和平台规范化事件 - -主要事件发布者（例如 AWS、Microsoft、Google 等）都在各自的平台上以不同的格式发布事件。 -甚至在少数情况下，同一提供商的服务以不同格式（例如 AWS）发布事件。 -这迫使事件消费者实现自定义逻辑以跨平台读取或处理事件数据，有时甚至需要跨单个平台的多个服务处理。 - -CloudEvents 可以为那些跨平台和服务处理事件的使用者提供单一体验。 - -#### 促进跨服务和平台的集成 - -跨环境传输的事件数据越来越普遍。 -然而，如果没有描述事件的通用方式，跨环境的事件传递就会受到阻碍。 -CloudEvents之前没有单一的方法可以确定事件的来源和可能的去向。 -这对研究成功传输事件事件工具和消费者知道如何处理事件数据形成了巨大阻碍。 - -CloudEvents 提供有用的元数据，中间件和消费者可以依赖这些元数据来促进事件路由、日志记录、传输和接收。 - -#### 提高功能即服务的可移植性 - -功能即服务（也称为serverless计算）是 IT 中增长最快的趋势之一，它主要是由事件驱动的。 -然而，FaaS 的一个主要问题是供应商锁定。 -这种锁定部分是由函数 API 和供应商之间签名的差异引起的， -锁定同样也是由函数内接收的事件数据格式的差异引起的。 - -CloudEvents提供描述事件数据的通用方式提高了功能即服务的可移植性。 - -#### 改进事件驱动/serverless架构的开发和测试 - -缺乏通用事件格式使事件驱动和serverless架构的开发和测试变得复杂。 -没有简单的方法可以准确地为开发和测试目的模拟事件，并帮助在开发环境中模拟事件驱动的工作流。 - -CloudEvents 可以提供更好的开发工具来构建、测试和处理事件驱动和无服务器架构的端到端生命周期。 - -#### 事件数据发展 - -大多数平台和服务对其事件的数据模型进行不同的版本控制（如果他们这样做的话）。 -随着这些数据模型的发展，这会为发布和使用事件的数据模型带来不一致的体验。 - -CloudEvents 可以提供一种通用的方式来版本化和演化事件数据的发展。 -这将帮助事件发布者根据最佳实践安全地对其数据模型进行版本控制， -并且这有助于事件消费者随着事件数据的发展安全地使用它。 - -#### 规范化 Webhook - -Webhooks 是一种不使用通用格式的来发布事件的模式。 -Webhook 的使用者没有一致的方式来开发、测试、识别、验证和整体处理通过 Webhook 传输的事件数据。 - -CloudEvents 可以提供 Webhook 发布和消费事件的一致性。 - -#### 安全策略 - -出于安全和策略考虑，可能需要过滤、转换或阻止系统之间的事件传输。 -比如可能需要防止事件的进入或退出，如包含敏感信息的事件数据或想要禁止发送方和接收方之间的信息流。 - -通用事件格式将允许更容易地推理正在传输的数据，并提供更好的数据自查。 - -#### 事件追踪 - -从源发送的事件可能会出现在一系列附加事件序列之中， -这些附加事件序列从各种中间件设备（例如事件代理和网关）发出。 -CloudEvents 在事件中包含元数据以将这些事件关联为事件序列的一部分，以便进行事件跟踪和故障排除。 - -#### IoT - -物联网设备会发送和接收与其功能相关的事件。 -例如，连接的恒温器将发送有关当前温度的遥测数据， -并可以接收改变温度的事件。 -这些设备通常具有受限的操作环境（cpu、内存），需要明确定义的事件消息格式。 -在很多情况下，这些消息是二进制编码的，而不是文本的。 -无论是直接来自设备还是通过网关转换，CloudEvents 都可以更好地描述消息的来源和消息中包含的数据格式。 - -#### 事件关联 - -一个serverless应用或工作流可能与来自不同事件源或事件生产者的多个事件相关联。 -例如，盗窃检测应用程序/工作流可能涉及运动事件和门/窗打开事件。 -一个serverless平台可能接收每种类型事件的许多实例，例如 它可以接收来自不同房屋的运动事件和开窗事件。 - -serverless平台需要将一种类型的事件实例与其他类型的事件实例正确关联， -并将接收到的事件实例映射到正确的应用/工作流实例。 -CloudEvents 将为任何事件使用者（例如serverless平台）提供一种标准方式， -以在事件数据中定位事件关联信息/令牌并将接收到的事件实例映射到正确的应用/工作流实例。 - -### 现有的数据格式 - -与上一节一样，对当前现状的调查（和理解）对CloudEvents 小组来说非常重要。 -为此，下面列出了在实践中被广泛使用的当前事件格式的样本。 - -#### Microsoft - Event Grid - -``` -{ - "topic":"/subscriptions/{subscription-id}", - "subject":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/eventSubscriptions/LogicAppdd584bdf-8347-49c9-b9a9-d1f980783501", - "eventType":"Microsoft.Resources.ResourceWriteSuccess", - "eventTime":"2017-08-16T03:54:38.2696833Z", - "id":"25b3b0d0-d79b-44d5-9963-440d4e6a9bba", - "data": { - "authorization":"{azure_resource_manager_authorizations}", - "claims":"{azure_resource_manager_claims}", - "correlationId":"54ef1e39-6a82-44b3-abc1-bdeb6ce4d3c6", - "httpRequest":"", - "resourceProvider":"Microsoft.EventGrid", - "resourceUri":"/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/eventSubscriptions/LogicAppdd584bdf-8347-49c9-b9a9-d1f980783501", - "operationName":"Microsoft.EventGrid/eventSubscriptions/write", - "status":"Succeeded", - "subscriptionId":"{subscription-id}", - "tenantId":"72f988bf-86f1-41af-91ab-2d7cd011db47" - } -} -``` - -[Documentation](https://docs.microsoft.com/en-us/azure/event-grid/event-schema) - -#### Google - Cloud Functions (potential future) - -``` -{ - "data": { - "@type": "types.googleapis.com/google.pubsub.v1.PubsubMessage", - "attributes": { - "foo": "bar", - }, - "messageId": "12345", - "publishTime": "2017-06-05T12:00:00.000Z", - "data": "somebase64encodedmessage" - }, - "context": { - "eventId": "12345", - "timestamp": "2017-06-05T12:00:00.000Z", - "eventTypeId": "google.pubsub.topic.publish", - "resource": { - "name": "projects/myProject/topics/myTopic", - "service": "pubsub.googleapis.com" - } - } -} -``` - -#### AWS - CloudWatch Events - -AWS 上的很大一部分事件处理系统都在使用这种格式。 - -``` -{ - "version": "0", - "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718", - "detail-type": "EC2 Instance State-change Notification", - "source": "aws.ec2", - "account": "111122223333", - "time": "2017-12-22T18:43:48Z", - "region": "us-west-1", - "resources": [ - "arn:aws:ec2:us-west-1:123456789012:instance/i-1234567890abcdef0" - ], - "detail": { - "instance-id": "i-1234567890abcdef0", - "state": "terminated" - } -} -``` - -#### IBM - OpenWhisk - Web Action Event - -``` -{ - "__ow_method": "post", - "__ow_headers": { - "accept": "*/*", - "connection": "close", - "content-length": "4", - "content-type": "text/plain", - "host": "172.17.0.1", - "user-agent": "curl/7.43.0" - }, - "__ow_path": "", - "__ow_body": "Jane" -} -``` - -#### OpenStack - Audit Middleware - Event - -``` -{ - "typeURI": "http://schemas.dmtf.org/cloud/audit/1.0/event", - "id": "d8304637-3f63-5092-9ab3-18c9781871a2", - "eventTime": "2018-01-30T10:46:16.740253+00:00", - "action": "delete", - "eventType": "activity", - "outcome": "success", - "reason": { - "reasonType": "HTTP", - "reasonCode": "204" - }, - "initiator": { - "typeURI": "service/security/account/user", - "name": "user1", - "domain": "domain1", - "id": "52d28347f0b4cf9cc1717c00adf41c74cc764fe440b47aacb8404670a7cd5d22", - "host": { - "address": "127.0.0.1", - "agent": "python-novaclient" - }, - "project_id": "ae63ddf2076d4342a56eb049e37a7621" - }, - "target": { - "typeURI": "compute/server", - "id": "b1b475fc-ef0a-4899-87f3-674ac0d56855" - }, - "observer": { - "typeURI": "service/compute", - "name": "nova", - "id": "1b5dbef1-c2e8-5614-888d-bb56bcf65749" - }, - "requestPath": "/v2/ae63ddf2076d4342a56eb049e37a7621/servers/b1b475fc-ef0a-4899-87f3-674ac0d56855" -} -``` - -[Documentation](https://github.com/openstack/pycadf/blob/master/doc/source/event_concept.rst) - -#### Adobe - I/O Events - -``` -{ - "event_id": "639fd17a-d0bb-40ca-83a4-e78612bce5dc", - "event": { - "@id": "82235bac-2b81-4e70-90b5-2bd1f04b5c7b", - "@type": "xdmCreated", - "xdmEventEnvelope:objectType": "xdmAsset", - "activitystreams:to": { - "xdmImsUser:id": "D13A1E7053E46A220A4C86E1@AdobeID", - "@type": "xdmImsUser" - }, - "activitystreams:generator": { - "xdmContentRepository:root": "https://cc-api-storage.adobe.io/", - "@type": "xdmContentRepository" - }, - "activitystreams:actor": { - "xdmImsUser:id": "D13A1E7053E46A220A4C86E1@AdobeID", - "@type": "xdmImsUser" - }, - "activitystreams:object": { - "@type": "xdmAsset", - "xdmAsset:asset_id": "urn:aaid:sc:us:4123ba4c-93a8-4c5d-b979-ffbbe4318185", - "xdmAsset:asset_name": "example.jpg", - "xdmAsset:etag": "6fc55d0389d856ae7deccebba54f110e", - "xdmAsset:path": "/MyFolder/example.jpg", - "xdmAsset:format": "image/jpeg" - }, - "activitystreams:published": "2016-07-16T19:20:30+01:00" - } -} -``` - -[Documentation](https://www.adobe.io/apis/cloudplatform/events/documentation.html) From 9e8dd6fc9b8ccafb509301e6e649cf038b954e9f Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:55:01 +0800 Subject: [PATCH 59/60] Create spec_CN.md Signed-off-by: JieDing --- Chinese Manual/spec_CN.md | 478 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 478 insertions(+) create mode 100644 Chinese Manual/spec_CN.md diff --git a/Chinese Manual/spec_CN.md b/Chinese Manual/spec_CN.md new file mode 100644 index 000000000..e27e009d3 --- /dev/null +++ b/Chinese Manual/spec_CN.md @@ -0,0 +1,478 @@ +# CloudEvents 核心规范- 1.0 版本 + +Declaration： This manual aims to provide a fast and brief introduction of CloudEvents +in Chinese for people who are new to CloudEvents. +Most of the content is translated from the original English version. +It is strongly recommended to read the English version if you find anything lost in translation. + +## 摘要 + +CloudEvents 是一个用于定义事件格式的供应商中立规范。 + +## 目录 + +- [概览](#概览) +- [符号和术语](#符号和术语) +- [上下文属性](#上下文属性) +- [事件数据](#事件数据) +- [大小限制](#大小限制) +- [隐私与安全](#隐私与安全) +- [示例](#示例) + +## 概览 + +事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 + +对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。 +它同样限制了那些用来帮助事件数据完成 跨环境传输的库(如SDKs)， +工具(如事件路由器)和基础设施(如事件追踪系统)的发展。 +总体来看，这种匮乏严重阻碍了事件数据的可移植性和生产力。 + +CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 + +事件格式指定如何使用某些编码格式序列化一个 CloudEvent。 +支持那些编码且兼容 CloudEvents 的实现必须遵守相应事件格式中指定的编码规则。 +所有实现都必须支持 [JSON 格式](json-format.md)。 + +有关规范背后的历史、开发和设计原理等更多信息， +请参阅 CloudEvents [入门文档](primer_CN.md)。 + +## 符号和术语 + +### 符号约定 + +本文档中的关键词 +"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 需要按照 +[RFC 2119](https://tools.ietf.org/html/rfc2119) 中的描述来理解。 + +为清楚起见， +当一个功能被标记为“OPTIONAL”时，这意味着消息的 +[生产者](#生产者)和[消费者](#消费者) 都可以自行选择是否支持该功能。 +换句话说，生产者可以在需要时在消息中包含该功能，消费者也可以在需要时选择支持该功能。 +不支持该功能的消费者将默默地忽略该部分消息。 +生产者需要做好消费者并没有启用该功能的准备。 +[中间人](#中间人) 应当转发OPTIONAL属性。 + +### 术语 + +本规范定义了下列术语 + +#### 发生 + +“发生”是指在软件系统运行期间对事实状态的捕获。 +这可能是由于系统发出了信号或系统观察到信号、状态更改、计时器超时 +或任何其他值得注意的活动而发生的。 +例如，设备可能会因为电池电量低或虚拟机即将执行计划的重启而进入警报状态。 + +#### 事件 + +“事件”是表示一条"发生"及其上下文的数据记录。 +事件从事件生产者（源）路由到对它感兴趣的事件消费者。 +事件中包含的信息帮助完成路由操作，但事件不会标识特定的路由目的地。 +事件将包含两种类型的信息：表示"发生"的 [事件数据](#事件数据) +和提供有关事件的环境信息的[上下文](#上下文) 元数据。 +一次"发生"可能导致多个事件的产生。 + +#### 生产者 + +“生产者”是一种特定的实例、进程或设备，它能够创建用来描述CloudEvent的数据结构。 + +#### 源 + +"源"是事件发生的上下文环境。在分布式系统中，它可能由多个生产者组成。 +如果一个源无法查看到CloudEvents，那么一定有有外部的生产者在代替源来生产CloudEvent。 + +#### 消费者 + +一个“消费者”会接收事件并根据事件采取一定的行为。 +它使用上下文环境和事件数据来执行一些逻辑，这可能会导致新事件的发生。 + +#### 中间人 + +一个“中间人”会接收包含事件的消息， +并将其转发给下一个接收者，但该接收者可能是另一个中间人或事件[消费者](#消费者)。 +中间人的典型任务就是根据[上下文](#上下文)环境中的信息将事件路由到接收者。 + +#### 上下文 + +上下文环境元数据被封装在[上下文-属性](#上下文-属性)中。 +工具和应用程序代码可以使用此信息来识别事件与系统方面或事件与其他事件的关系。 + +#### 数据 + +关于事件的特定域信息（即有效负载）。这可能包括有关事件的信息、有关已更改数据的详细信息等。 +有关更多信息，请参阅[事件数据](#事件数据)部分。 + +#### 事件格式 + +一个事件格式会指定如何将 CloudEvent 序列化为字节序列。 +独立事件格式（例如 [JSON 格式](json-format.md)）指定独立于任何协议或存储介质的序列化。 +协议绑定可以定义依赖于协议的格式。 + +#### 消息 + +事件通过消息从源传输到目标。 + +“结构化模式消息”是一种使用独立事件格式对事件进行完全编码并存储在消息体中的消息。 + +“二进制模式消息”会将事件数据存储在消息体中，并将事件属性作为消息元数据的一部分存储下来。 + +#### 协议 + +消息可以通过各种行业标准协议 +（例如 HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或平台/供应商 +专有协议（AWS Kinesis、Azure 事件网格）传输。 + +#### 协议绑定 + +协议绑定描述了如何通过给定协议发送和接收事件，特别是如何将事件映射到该协议的消息中去。 + +## 上下文属性 + +每个符合本规范的 CloudEvent 必须包括指定为 REQUIRED 的上下文属性， +可以包括一个或多个OPTIONAL上下文属性， +并且可以包括一个或多个扩展属性。 + +这些属性虽然描述了事件，但被设计为可以独立于事件数据进行序列化。 +这允许在不反序列化事件数据的情况下，在目的检查这些上下文属性。 + +### 属性命名约定 + +CloudEvents 规范定义了到各种协议和编码的映射，随附的 CloudEvents SDK 面向各种运行时和编程语言。 +其中一些将元数据元素区分大小写，而另一些则不区分， +并且单个 CloudEvent 可能通过涉及到协议、编码和运行时混合的多个跃点进行路由。 +因此，本规范限制了所有属性的可用字符集，以防止区分大小写问题或与通用语言中标识符的合法字符集冲突问题。 + +CloudEvents 属性名称必须由来自 ASCII 字符集的小写字母（“a”到“z”）或数字（“0”到“9”）组成。 +属性名称应该是描述性的和简洁的，并且长度不应超过 20 个字符。 + +### 类型系统 + +以下抽象数据类型可用于属性。 +这些类型中的每一种都可以由不同的事件格式和协议元数据字段以不同的方式表示。 +本规范为所有实现必须支持的每种类型定义了规范的字符串编码。 + +- `Boolean` - “true”或“false”的布尔值。 + - 字符串编码：区分大小写的`true` 或 `false`值。 +- `Integer` -范围在 -2,147,483,648 到 +2,147,483,647 （包含）之间的整数。 + 这是有符号 32 位二进制补码编码的范围。 + 事件格式不必使用此编码，但它们必须使用在此范围内的`Integer` 值。 + - 字符串编码: 符合 + [RFC 7159, 第 6 节](https://tools.ietf.org/html/rfc7159#section-6) + JSON 数字的整数部分 +- `String` - 允许的 Unicode 字符序列。 不允许使用以下字符： + - 范围 U+0000-U+001F 和 U+007F-U+009F（包含首尾）中的“控制字符”， + 因为大多数没有商定的含义，还有一些，例如 U+000A（换行符）， 在如 HTTP 头部之类的上下文中不可用。 + -[被 Unicode 标识为非字符的](http://www.unicode.org/faq/private_use.html#noncharacters) + 代码点。 + - 被 Unicode 标识为代理项的代码点, 范围 U+D800-U+DBFF 和 U+DC00-U+DFFF（包含首尾） + , 除非被合理的用作代理对. 因此（在 JSON 符号中） + “\uDEAD”是无效的，因为它是一个未配对的代理，而“\uD800\uDEAD”是合法的。 +- `Binary` - 字节序列. + - 字符串编码: 基于 + [RFC4648](https://tools.ietf.org/html/rfc4648) 的Base64 编码。 +- `URI` - 绝对统一资源标识符。 + - 字符串编码: + [RFC 3986 第 4.3 节](https://tools.ietf.org/html/rfc3986#section-4.3) + 中定义的 `Absolute URI` 。 +- `URI-reference` - 统一资源标识符引用。 + - 字符串编码: + [RFC 3986 第 4.1 节](https://tools.ietf.org/html/rfc3986#section-4.1) + 中定义的`URI-reference` 。 +- `Timestamp` - 使用公历的日期和时间表达式。 + - 字符串编码: [RFC 3339](https://tools.ietf.org/html/rfc3339) 。 + +所有上下文属性值必须是上面列出的类型之一。 +属性值可以表示为原生类型或规范字符串。 + +当强类型编程语言表示 CloudEvent 或任何扩展时， +必须能够在规范字符串编码与对应抽象类型的运行时/编程语言类型之间进行转换。 + +例如，在给定的实现中，`time` 属性可能由编程语言的本地时间类型表示， +但它必须是可设置提供 RFC3339 字符串的， +并且当映射到 HTTP 消息头时，它必须可转换为 RFC3339 字符串。 + +CloudEvents 协议绑定或事件格式实现同样必须能够 +在规范字符串编码与协议元数据字段中的对应数据类型之间进行转换。 + +`Timestamp` 类型的属性值确实可能以字符串形式路由通过多个跃点， +并且仅在生产者和最终消费者处实现为本地运行时/语言类型。 +`Timestamp` 类型也可以作为本机协议类型路由， +并且可以在生产者和消费者端映射到/从各自的语言/运行时类型，但永远不会转为字符串格式。 + +序列化机制的选择将决定上下文属性和事件数据将如何序列化。 +例如，在 JSON 序列化的情况下，上下文属性和事件数据可能都出现在同一个 JSON 对象中。 + +### 必要属性 + +下列属性必须自所有的 CloudEvents 中展示： + +#### id + +- 类型: `String` +- 描述: 标识一个事件。 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 + 如果重复的事件被重新发送（例如由于网络错误），它可能具有相同的 `id`。 + Consumers MAY assume that + 消费者可以假设具有相同`source` 和 `id`的事件是重复的。 +- 示例: + - 一个由生产者维护的事件计数器 + - 一个 UUID +- 约束条件: + - 必要的 + - 必须是非空字符串 + - 在生产者的范围内必须是唯一的 + +#### source + +- 类型: `URI-reference` +- 描述: 标识事件发生的上下文背景。 这通常包括诸如事件源类型、发布事件的组织 + 或产生事件的过程等信息。URI 中编码的数据背后的确切语法和语义由事件生产者定义。 + + 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 + + 应用程序可以为每个不同的生产者分配一个唯一的`source`， + 这使得生成唯一 ID 变得容易，因为没有其他生产者将拥有相同的来源。 + 应用程序可以使用 UUIDs、URNs、DNS权威机构或特定于应用程序的方案来创建唯一的`source` 标识符。 + + 一个来源可以包括多个生产者。 + 在这种情况下，生产者必须协作以确保每个不同事件的 `source` + `id`都是唯一的。 + +- 约束条件: + - 必要的 + - 必须是非空 URI-reference + - 推荐使用 绝对 URI +- 示例 + - 具有 DNS 权限的 Internet 范围唯一 URI： + - https://github.com/cloudevents + - mailto:cncf-wg-serverless@lists.cncf.io + - 具有 UUID 的通用唯一 URN： + - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 + - 应用程序专有的标识符 + - /cloudevents/spec/pull/123 + - /sensors/tn-1234567/alerts + - 1-555-123-4567 + +#### specversion + +- 类型: `String` +- 描述: 事件使用的 CloudEvents 规范的版本。 + 这让解释上下文环境更容易。 + 当引用这个版本的规范时，兼容的事件生产者必须使用 `1.0` 的值。 +- 约束条件: + - 必要的 + - 必须是非空字符串 + +#### type + +- 类型: `String` +- 描述: 该属性包含一个值，描述与原始事件相关的事件类型。 + 该属性通常用于路由、可观察性、策略实施等。其格式是生产者定义的，可能包括诸如 `type`版本之类的信息 + -从 + [入门文档-属性版本控制](primer_CN.md#属性版本控制) 中获得更多信息 + +- 约束条件: + - 必要的 + - 必须是非空字符串 + - 应该以反向 DNS 名称作为前缀。该前缀域表明了定义此事件类型语义的组织。 +- 示例 + - com.github.pull.create + - com.example.object.delete.v2 + +### 可选属性 + +下列属性在 CloudEvents 中是可选的. 在 +[符号约定](#notational-conventions) 中查看更多 OPTIONAL 定义的信息。 + +#### datacontenttype + +- 类型: `String` [RFC 2046](https://tools.ietf.org/html/rfc2046) +- 描述: `data`值的内容类型。 此属性使`data`能够承载任何类型的内容， + 因此格式和编码可能与所选事件格式的不同。 + 例如，使用 [JSON envelope](./json-format.md#3-envelope) + 格式呈现的事件可能在数据中携带 XML 的payload，这个属性可以用来通知消费者 + 设置"application/xml"。 + 关于`data`内容如何提供不同的`datacontenttype`的值的规则在事件格式规范中定义。 + 例如，JSON 事件格式定义了 [3.1 节](./json-format.md#31-handling-of-data)中的关系。 + 对于某些二进制模式协议绑定， + 此字段直接能映射到相应协议的内容类型的元数据属性上。 + 二进制模式和内容类型元数据映射的规范规则可以在各自的协议中找到。 + + 在某些事件格式中，可以省略 `datacontenttype` 属性。 + 例如，如果 JSON 格式的事件没有 `datacontenttype` 属性， + 则表示该`data`是符合“application/json”媒体类型的 JSON 值。 + 换句话说：一个没有 `datacontenttype` 的 JSON 格式的事件完全等同于 + 一个带有 `datacontenttype="application/json"`的事件。 + + 当将没有 `datacontenttype` 属性的事件消息转换为不同的格式或协议绑定时， + 目标 `datacontenttype` 应该显式设置为事件源的隐含或默认的 `datacontenttype`。 + +- 约束条件: + - 可选的 + - 若有则必须遵守 + [RFC 2046](https://tools.ietf.org/html/rfc2046) 制定的格式 +- 媒体类型示例 + [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml) + +#### dataschema + +- 类型: `URI` +- 描述: 标识 `data` 遵守的规范。 对模式的不兼容的更改应该由不同的 URI 体现。 在 + [入门文档-属性版本控制](primer_CN.md#属性版本控制) + 中查看更多信息。 +- 约束条件: + - 可选的 + - 若有必须是非空的 URI + +#### subject + +- 类型: `String` +- 描述: 这个属性描述了事件生产者 (由`source`标识) 上下文环境中的主题信息。 + 在发布-订阅场景中，订阅者通常会订阅`source`发出的事件， + 但如果`source` 的上下文环境具有内部子结构， + 则单独的`source`标识符可能不足以作为任何指定事件的限定符。 + + 在上下文元数据中识别事件的主题（与仅在数据负载中相反） + 对于中间件无法解释`data` 内容的通用订阅过滤场景特别有用。 + 在上面的示例中，订阅者可能只对名称以“.jpg”或“.jpeg”结尾的blob感兴趣， + 此时`subject` 属性允许为该事件子集构建简单有效的字符串后缀过滤器。 + +- 约束条件: + - 可选的 + - 若有必须是非空字符串 +- 示例: + - 订阅者可能对在blob在blob存储容器中创建的时候感兴趣并订阅。 + 在这个场景下，事件`source`标示出订阅的范围（存储容器），`type` 标识出 + blob 创建" 这个事件，`id` 唯一标识出事件示例，以区分已创建同名blob的事件， + 而新创建的blob的名字可以放在`subject`属性中： + - `source`: https://example.com/storage/tenant/container + - `subject`: mynewfile.jpg + +#### time + +- 类型: `Timestamp` +- 描述: 事件发生的时间戳。 + 如果无法确定发生的时间，则 CloudEvents 生产者可以将此属性设置为其他时间（例如当前时间）。 + 但是在这方面，同一`source`的所有生产者必须保持一致。 + 换句话说，要么它们都使用发生的实际时间，要么它们都使用相同的算法来确定所使用的值。 + +- 约束条件: + - 可选的 + - 若有则必须遵守 + [RFC 3339](https://tools.ietf.org/html/rfc3339) + +### 扩展上下文属性 + +CloudEvent 可以包含任意数量的具有不同名称的附加上下文属性，被称为"扩展属性"。 +扩展属性必须遵循相同的[命名约定](#属性命名约定)并使用与标准属性相同的 +[类型系统](#类型系统)。 +扩展属性在本规范中没有定义好的含义， +它们允许外部系统将元数据附加到事件，就像 HTTP 自定义头部一样。 + +扩展属性总是如标准属性一样，根据绑定规则进行序列化。 +然而，该规范不阻止扩展将事件属性值复制到消息的其他部分， +以便与也其它处理消息的非 CloudEvents 系统进行交互。 +如果复制的值与云事件序列化值不同，执行此操作的扩展规范应该指定接收者如何解释消息。 + +#### 定义扩展 + +在 +[CloudEvent-属性扩展](primer_CN.md#CloudEvent-属性扩展) +查阅有关扩展使用和定义等相关信息。 + +扩展的定义应该完全定义属性的方方面面——例如 它的名称、类型、语义含义和可能的值。 +新的扩展定义应该使用一个足够描述性的名称来减少与其他扩展的名称冲突的机会。 +特别是，扩展作者应该检查[扩展文件](documented-extensions.md)中 +已知的扩展集——不仅是可能的名称冲突，还有相同目的冲突的扩展。 + +许多协议为发送者提供了包含额外元数据的能力，例如作为 HTTP 头部。 +虽然没有强制要求 CloudEvents 接受者处理和传递它们， +但建议接受者通过某种机制进行处理，以明确它们是非 CloudEvents 的元数据。 + +下面是一个示例，说明了 CloudEvents 对附加属性的需求。 +在许多物联网和企业用例中，事件可用于跨多种类型事件执行操作的serverless应用程序中。 +为了支持这样的用例，事件生产者需要向“上下文属性”添加额外的身份属性， +事件消费者可以使用这些属性将这个事件与其他事件相关联。 +如果此类身份属性恰好是事件“数据”的一部分， +则事件生产者还会将身份属性添加到“上下文属性”中， +以便事件消费者可以轻松访问此信息，而无需解码和检查事件数据。 +此类身份属性还可用于帮助中间网关确定如何路由事件。 + +## 事件数据 + +正如[数据](#数据)所定义的那样，CloudEvents 可以包括有关事件的特定域的信息。 +这些信息将被封装在`data`中。 + +- 描述: 事件负载。 本规范对该信息的类型不作任何限制。 + 它被编码为一种媒体格式，这种格式由`datacontenttype` 属性(如 application/json)指定， + 并在存在这些相应属性时遵循`dataschema`格式。 + It is encoded into a media format + +- 约束条件: + - 可选的 + +# 大小限制 + +在很多情况下，CloudEvents 将通过一个或多个通用中间人进行转发， +每个中间人都可能对转发事件的大小施加限制。 +CloudEvents 也可能直接被路由到消费者，如嵌入式设备， +这些设备是受存储或内存限制的，对单个大型事件表现不佳。 + +事件的“大小”是它的线路大小，包括在线路上为事件传输的每一位： +协议帧元数据、事件元数据和事件数据，基于所选的事件格式和所选的协议绑定。 + +如果应用程序配置需要跨不同协议路由事件或重新编码事件， +应用程序能使用的效率最低的协议和编码，都修腰符合这些大小限制： + +- 中间人转发的事件大小必须为 64 KB 或更小。 +- 消费者应该能接受大小至少为 64 KB 的事件。 + +为了方便，上述规则将允许生产者安全地发布最大 64KB 的事件。 +这里的安全意味着生产者期望事件被所有中间人接受并合理地转发。 +它是在任何特定消费者的控制之下，无论消费者是否由于本地考虑而选择接受或拒绝该大小的事件。 + +通常，CloudEvents 发布者应该通过避免将大型数据项嵌入到事件而使用事件有效链接到此类数据项， +来保持事件紧凑。 +从访问控制的角度来看，这种方法对更广泛的事件分布式化有帮助， +因为通过解析链接访问与事件相关的细节能实现差异化访问控制和选择性披露， +而不是将敏感详细数据直接嵌入到事件中。 + +# 隐私与安全 + +互操作性是本规范背后的主要驱动力， +实现此目标需要一些信息明确可用，这可能导致信息的泄漏。 + +考虑以下事项以防止信息意外泄漏，尤其是在利用第三方平台和通信网络时： + +- 上下文属性 + + 敏感信息不应在上下文属性中携带。 + + CloudEvent 生产者、消费者和中间人可以自查并记录下上下文属性。 + +- 数据 + + 特定的[事件数据](#事件数据) 应该被加密以限制对受信任方的可见性。 + 用于这种加密的机制是生产者和消费者之间的协议，不在本规范的讨论范围内。 + +- 协议绑定 + 应该采用协议级别的安全性机制来确保 CloudEvents 完成可信和安全的交换。 + +# 示例 + +以下示例展示了一个序列化为 JSON 的 CloudEvent： + +```JSON +{ + "specversion" : "1.0", + "type" : "com.github.pull.create", + "source" : "https://github.com/cloudevents/spec/pull", + "subject" : "123", + "id" : "A234-1234-1234", + "time" : "2018-04-05T17:31:00Z", + "comexampleextension1" : "value", + "comexampleothervalue" : 5, + "datacontenttype" : "text/xml", + "data" : "" +} +``` From 9c3d5251077a3fb06126b447657e2a6cb3feb8f5 Mon Sep 17 00:00:00 2001 From: JieDing Date: Tue, 9 Nov 2021 16:55:28 +0800 Subject: [PATCH 60/60] Delete spec_CN.md Signed-off-by: JieDing --- spec_CN.md | 478 ----------------------------------------------------- 1 file changed, 478 deletions(-) delete mode 100644 spec_CN.md diff --git a/spec_CN.md b/spec_CN.md deleted file mode 100644 index e27e009d3..000000000 --- a/spec_CN.md +++ /dev/null @@ -1,478 +0,0 @@ -# CloudEvents 核心规范- 1.0 版本 - -Declaration： This manual aims to provide a fast and brief introduction of CloudEvents -in Chinese for people who are new to CloudEvents. -Most of the content is translated from the original English version. -It is strongly recommended to read the English version if you find anything lost in translation. - -## 摘要 - -CloudEvents 是一个用于定义事件格式的供应商中立规范。 - -## 目录 - -- [概览](#概览) -- [符号和术语](#符号和术语) -- [上下文属性](#上下文属性) -- [事件数据](#事件数据) -- [大小限制](#大小限制) -- [隐私与安全](#隐私与安全) -- [示例](#示例) - -## 概览 - -事件(Events)在现代系统中无处不在。但不同的事件生产者往往用不同的规范来描述自己的事件。 - -对事件的统一描述的匮乏意味着开发者必须不断重新学习如何消费不同定义的事件。 -它同样限制了那些用来帮助事件数据完成 跨环境传输的库(如SDKs)， -工具(如事件路由器)和基础设施(如事件追踪系统)的发展。 -总体来看，这种匮乏严重阻碍了事件数据的可移植性和生产力。 - -CloudEvents是一个以通用格式来描述事件数据的标准。它提供了事件在服务、平台和系统中的互操作性。 - -事件格式指定如何使用某些编码格式序列化一个 CloudEvent。 -支持那些编码且兼容 CloudEvents 的实现必须遵守相应事件格式中指定的编码规则。 -所有实现都必须支持 [JSON 格式](json-format.md)。 - -有关规范背后的历史、开发和设计原理等更多信息， -请参阅 CloudEvents [入门文档](primer_CN.md)。 - -## 符号和术语 - -### 符号约定 - -本文档中的关键词 -"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" 需要按照 -[RFC 2119](https://tools.ietf.org/html/rfc2119) 中的描述来理解。 - -为清楚起见， -当一个功能被标记为“OPTIONAL”时，这意味着消息的 -[生产者](#生产者)和[消费者](#消费者) 都可以自行选择是否支持该功能。 -换句话说，生产者可以在需要时在消息中包含该功能，消费者也可以在需要时选择支持该功能。 -不支持该功能的消费者将默默地忽略该部分消息。 -生产者需要做好消费者并没有启用该功能的准备。 -[中间人](#中间人) 应当转发OPTIONAL属性。 - -### 术语 - -本规范定义了下列术语 - -#### 发生 - -“发生”是指在软件系统运行期间对事实状态的捕获。 -这可能是由于系统发出了信号或系统观察到信号、状态更改、计时器超时 -或任何其他值得注意的活动而发生的。 -例如，设备可能会因为电池电量低或虚拟机即将执行计划的重启而进入警报状态。 - -#### 事件 - -“事件”是表示一条"发生"及其上下文的数据记录。 -事件从事件生产者（源）路由到对它感兴趣的事件消费者。 -事件中包含的信息帮助完成路由操作，但事件不会标识特定的路由目的地。 -事件将包含两种类型的信息：表示"发生"的 [事件数据](#事件数据) -和提供有关事件的环境信息的[上下文](#上下文) 元数据。 -一次"发生"可能导致多个事件的产生。 - -#### 生产者 - -“生产者”是一种特定的实例、进程或设备，它能够创建用来描述CloudEvent的数据结构。 - -#### 源 - -"源"是事件发生的上下文环境。在分布式系统中，它可能由多个生产者组成。 -如果一个源无法查看到CloudEvents，那么一定有有外部的生产者在代替源来生产CloudEvent。 - -#### 消费者 - -一个“消费者”会接收事件并根据事件采取一定的行为。 -它使用上下文环境和事件数据来执行一些逻辑，这可能会导致新事件的发生。 - -#### 中间人 - -一个“中间人”会接收包含事件的消息， -并将其转发给下一个接收者，但该接收者可能是另一个中间人或事件[消费者](#消费者)。 -中间人的典型任务就是根据[上下文](#上下文)环境中的信息将事件路由到接收者。 - -#### 上下文 - -上下文环境元数据被封装在[上下文-属性](#上下文-属性)中。 -工具和应用程序代码可以使用此信息来识别事件与系统方面或事件与其他事件的关系。 - -#### 数据 - -关于事件的特定域信息（即有效负载）。这可能包括有关事件的信息、有关已更改数据的详细信息等。 -有关更多信息，请参阅[事件数据](#事件数据)部分。 - -#### 事件格式 - -一个事件格式会指定如何将 CloudEvent 序列化为字节序列。 -独立事件格式（例如 [JSON 格式](json-format.md)）指定独立于任何协议或存储介质的序列化。 -协议绑定可以定义依赖于协议的格式。 - -#### 消息 - -事件通过消息从源传输到目标。 - -“结构化模式消息”是一种使用独立事件格式对事件进行完全编码并存储在消息体中的消息。 - -“二进制模式消息”会将事件数据存储在消息体中，并将事件属性作为消息元数据的一部分存储下来。 - -#### 协议 - -消息可以通过各种行业标准协议 -（例如 HTTP、AMQP、MQTT、SMTP）、开源协议（例如 Kafka、NATS）或平台/供应商 -专有协议（AWS Kinesis、Azure 事件网格）传输。 - -#### 协议绑定 - -协议绑定描述了如何通过给定协议发送和接收事件，特别是如何将事件映射到该协议的消息中去。 - -## 上下文属性 - -每个符合本规范的 CloudEvent 必须包括指定为 REQUIRED 的上下文属性， -可以包括一个或多个OPTIONAL上下文属性， -并且可以包括一个或多个扩展属性。 - -这些属性虽然描述了事件，但被设计为可以独立于事件数据进行序列化。 -这允许在不反序列化事件数据的情况下，在目的检查这些上下文属性。 - -### 属性命名约定 - -CloudEvents 规范定义了到各种协议和编码的映射，随附的 CloudEvents SDK 面向各种运行时和编程语言。 -其中一些将元数据元素区分大小写，而另一些则不区分， -并且单个 CloudEvent 可能通过涉及到协议、编码和运行时混合的多个跃点进行路由。 -因此，本规范限制了所有属性的可用字符集，以防止区分大小写问题或与通用语言中标识符的合法字符集冲突问题。 - -CloudEvents 属性名称必须由来自 ASCII 字符集的小写字母（“a”到“z”）或数字（“0”到“9”）组成。 -属性名称应该是描述性的和简洁的，并且长度不应超过 20 个字符。 - -### 类型系统 - -以下抽象数据类型可用于属性。 -这些类型中的每一种都可以由不同的事件格式和协议元数据字段以不同的方式表示。 -本规范为所有实现必须支持的每种类型定义了规范的字符串编码。 - -- `Boolean` - “true”或“false”的布尔值。 - - 字符串编码：区分大小写的`true` 或 `false`值。 -- `Integer` -范围在 -2,147,483,648 到 +2,147,483,647 （包含）之间的整数。 - 这是有符号 32 位二进制补码编码的范围。 - 事件格式不必使用此编码，但它们必须使用在此范围内的`Integer` 值。 - - 字符串编码: 符合 - [RFC 7159, 第 6 节](https://tools.ietf.org/html/rfc7159#section-6) - JSON 数字的整数部分 -- `String` - 允许的 Unicode 字符序列。 不允许使用以下字符： - - 范围 U+0000-U+001F 和 U+007F-U+009F（包含首尾）中的“控制字符”， - 因为大多数没有商定的含义，还有一些，例如 U+000A（换行符）， 在如 HTTP 头部之类的上下文中不可用。 - -[被 Unicode 标识为非字符的](http://www.unicode.org/faq/private_use.html#noncharacters) - 代码点。 - - 被 Unicode 标识为代理项的代码点, 范围 U+D800-U+DBFF 和 U+DC00-U+DFFF（包含首尾） - , 除非被合理的用作代理对. 因此（在 JSON 符号中） - “\uDEAD”是无效的，因为它是一个未配对的代理，而“\uD800\uDEAD”是合法的。 -- `Binary` - 字节序列. - - 字符串编码: 基于 - [RFC4648](https://tools.ietf.org/html/rfc4648) 的Base64 编码。 -- `URI` - 绝对统一资源标识符。 - - 字符串编码: - [RFC 3986 第 4.3 节](https://tools.ietf.org/html/rfc3986#section-4.3) - 中定义的 `Absolute URI` 。 -- `URI-reference` - 统一资源标识符引用。 - - 字符串编码: - [RFC 3986 第 4.1 节](https://tools.ietf.org/html/rfc3986#section-4.1) - 中定义的`URI-reference` 。 -- `Timestamp` - 使用公历的日期和时间表达式。 - - 字符串编码: [RFC 3339](https://tools.ietf.org/html/rfc3339) 。 - -所有上下文属性值必须是上面列出的类型之一。 -属性值可以表示为原生类型或规范字符串。 - -当强类型编程语言表示 CloudEvent 或任何扩展时， -必须能够在规范字符串编码与对应抽象类型的运行时/编程语言类型之间进行转换。 - -例如，在给定的实现中，`time` 属性可能由编程语言的本地时间类型表示， -但它必须是可设置提供 RFC3339 字符串的， -并且当映射到 HTTP 消息头时，它必须可转换为 RFC3339 字符串。 - -CloudEvents 协议绑定或事件格式实现同样必须能够 -在规范字符串编码与协议元数据字段中的对应数据类型之间进行转换。 - -`Timestamp` 类型的属性值确实可能以字符串形式路由通过多个跃点， -并且仅在生产者和最终消费者处实现为本地运行时/语言类型。 -`Timestamp` 类型也可以作为本机协议类型路由， -并且可以在生产者和消费者端映射到/从各自的语言/运行时类型，但永远不会转为字符串格式。 - -序列化机制的选择将决定上下文属性和事件数据将如何序列化。 -例如，在 JSON 序列化的情况下，上下文属性和事件数据可能都出现在同一个 JSON 对象中。 - -### 必要属性 - -下列属性必须自所有的 CloudEvents 中展示： - -#### id - -- 类型: `String` -- 描述: 标识一个事件。 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 - 如果重复的事件被重新发送（例如由于网络错误），它可能具有相同的 `id`。 - Consumers MAY assume that - 消费者可以假设具有相同`source` 和 `id`的事件是重复的。 -- 示例: - - 一个由生产者维护的事件计数器 - - 一个 UUID -- 约束条件: - - 必要的 - - 必须是非空字符串 - - 在生产者的范围内必须是唯一的 - -#### source - -- 类型: `URI-reference` -- 描述: 标识事件发生的上下文背景。 这通常包括诸如事件源类型、发布事件的组织 - 或产生事件的过程等信息。URI 中编码的数据背后的确切语法和语义由事件生产者定义。 - - 生产者必须确保每个不同事件的 `source` + `id` 是唯一的。 - - 应用程序可以为每个不同的生产者分配一个唯一的`source`， - 这使得生成唯一 ID 变得容易，因为没有其他生产者将拥有相同的来源。 - 应用程序可以使用 UUIDs、URNs、DNS权威机构或特定于应用程序的方案来创建唯一的`source` 标识符。 - - 一个来源可以包括多个生产者。 - 在这种情况下，生产者必须协作以确保每个不同事件的 `source` + `id`都是唯一的。 - -- 约束条件: - - 必要的 - - 必须是非空 URI-reference - - 推荐使用 绝对 URI -- 示例 - - 具有 DNS 权限的 Internet 范围唯一 URI： - - https://github.com/cloudevents - - mailto:cncf-wg-serverless@lists.cncf.io - - 具有 UUID 的通用唯一 URN： - - urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 - - 应用程序专有的标识符 - - /cloudevents/spec/pull/123 - - /sensors/tn-1234567/alerts - - 1-555-123-4567 - -#### specversion - -- 类型: `String` -- 描述: 事件使用的 CloudEvents 规范的版本。 - 这让解释上下文环境更容易。 - 当引用这个版本的规范时，兼容的事件生产者必须使用 `1.0` 的值。 -- 约束条件: - - 必要的 - - 必须是非空字符串 - -#### type - -- 类型: `String` -- 描述: 该属性包含一个值，描述与原始事件相关的事件类型。 - 该属性通常用于路由、可观察性、策略实施等。其格式是生产者定义的，可能包括诸如 `type`版本之类的信息 - -从 - [入门文档-属性版本控制](primer_CN.md#属性版本控制) 中获得更多信息 - -- 约束条件: - - 必要的 - - 必须是非空字符串 - - 应该以反向 DNS 名称作为前缀。该前缀域表明了定义此事件类型语义的组织。 -- 示例 - - com.github.pull.create - - com.example.object.delete.v2 - -### 可选属性 - -下列属性在 CloudEvents 中是可选的. 在 -[符号约定](#notational-conventions) 中查看更多 OPTIONAL 定义的信息。 - -#### datacontenttype - -- 类型: `String` [RFC 2046](https://tools.ietf.org/html/rfc2046) -- 描述: `data`值的内容类型。 此属性使`data`能够承载任何类型的内容， - 因此格式和编码可能与所选事件格式的不同。 - 例如，使用 [JSON envelope](./json-format.md#3-envelope) - 格式呈现的事件可能在数据中携带 XML 的payload，这个属性可以用来通知消费者 - 设置"application/xml"。 - 关于`data`内容如何提供不同的`datacontenttype`的值的规则在事件格式规范中定义。 - 例如，JSON 事件格式定义了 [3.1 节](./json-format.md#31-handling-of-data)中的关系。 - 对于某些二进制模式协议绑定， - 此字段直接能映射到相应协议的内容类型的元数据属性上。 - 二进制模式和内容类型元数据映射的规范规则可以在各自的协议中找到。 - - 在某些事件格式中，可以省略 `datacontenttype` 属性。 - 例如，如果 JSON 格式的事件没有 `datacontenttype` 属性， - 则表示该`data`是符合“application/json”媒体类型的 JSON 值。 - 换句话说：一个没有 `datacontenttype` 的 JSON 格式的事件完全等同于 - 一个带有 `datacontenttype="application/json"`的事件。 - - 当将没有 `datacontenttype` 属性的事件消息转换为不同的格式或协议绑定时， - 目标 `datacontenttype` 应该显式设置为事件源的隐含或默认的 `datacontenttype`。 - -- 约束条件: - - 可选的 - - 若有则必须遵守 - [RFC 2046](https://tools.ietf.org/html/rfc2046) 制定的格式 -- 媒体类型示例 - [IANA Media Types](http://www.iana.org/assignments/media-types/media-types.xhtml) - -#### dataschema - -- 类型: `URI` -- 描述: 标识 `data` 遵守的规范。 对模式的不兼容的更改应该由不同的 URI 体现。 在 - [入门文档-属性版本控制](primer_CN.md#属性版本控制) - 中查看更多信息。 -- 约束条件: - - 可选的 - - 若有必须是非空的 URI - -#### subject - -- 类型: `String` -- 描述: 这个属性描述了事件生产者 (由`source`标识) 上下文环境中的主题信息。 - 在发布-订阅场景中，订阅者通常会订阅`source`发出的事件， - 但如果`source` 的上下文环境具有内部子结构， - 则单独的`source`标识符可能不足以作为任何指定事件的限定符。 - - 在上下文元数据中识别事件的主题（与仅在数据负载中相反） - 对于中间件无法解释`data` 内容的通用订阅过滤场景特别有用。 - 在上面的示例中，订阅者可能只对名称以“.jpg”或“.jpeg”结尾的blob感兴趣， - 此时`subject` 属性允许为该事件子集构建简单有效的字符串后缀过滤器。 - -- 约束条件: - - 可选的 - - 若有必须是非空字符串 -- 示例: - - 订阅者可能对在blob在blob存储容器中创建的时候感兴趣并订阅。 - 在这个场景下，事件`source`标示出订阅的范围（存储容器），`type` 标识出 - blob 创建" 这个事件，`id` 唯一标识出事件示例，以区分已创建同名blob的事件， - 而新创建的blob的名字可以放在`subject`属性中： - - `source`: https://example.com/storage/tenant/container - - `subject`: mynewfile.jpg - -#### time - -- 类型: `Timestamp` -- 描述: 事件发生的时间戳。 - 如果无法确定发生的时间，则 CloudEvents 生产者可以将此属性设置为其他时间（例如当前时间）。 - 但是在这方面，同一`source`的所有生产者必须保持一致。 - 换句话说，要么它们都使用发生的实际时间，要么它们都使用相同的算法来确定所使用的值。 - -- 约束条件: - - 可选的 - - 若有则必须遵守 - [RFC 3339](https://tools.ietf.org/html/rfc3339) - -### 扩展上下文属性 - -CloudEvent 可以包含任意数量的具有不同名称的附加上下文属性，被称为"扩展属性"。 -扩展属性必须遵循相同的[命名约定](#属性命名约定)并使用与标准属性相同的 -[类型系统](#类型系统)。 -扩展属性在本规范中没有定义好的含义， -它们允许外部系统将元数据附加到事件，就像 HTTP 自定义头部一样。 - -扩展属性总是如标准属性一样，根据绑定规则进行序列化。 -然而，该规范不阻止扩展将事件属性值复制到消息的其他部分， -以便与也其它处理消息的非 CloudEvents 系统进行交互。 -如果复制的值与云事件序列化值不同，执行此操作的扩展规范应该指定接收者如何解释消息。 - -#### 定义扩展 - -在 -[CloudEvent-属性扩展](primer_CN.md#CloudEvent-属性扩展) -查阅有关扩展使用和定义等相关信息。 - -扩展的定义应该完全定义属性的方方面面——例如 它的名称、类型、语义含义和可能的值。 -新的扩展定义应该使用一个足够描述性的名称来减少与其他扩展的名称冲突的机会。 -特别是，扩展作者应该检查[扩展文件](documented-extensions.md)中 -已知的扩展集——不仅是可能的名称冲突，还有相同目的冲突的扩展。 - -许多协议为发送者提供了包含额外元数据的能力，例如作为 HTTP 头部。 -虽然没有强制要求 CloudEvents 接受者处理和传递它们， -但建议接受者通过某种机制进行处理，以明确它们是非 CloudEvents 的元数据。 - -下面是一个示例，说明了 CloudEvents 对附加属性的需求。 -在许多物联网和企业用例中，事件可用于跨多种类型事件执行操作的serverless应用程序中。 -为了支持这样的用例，事件生产者需要向“上下文属性”添加额外的身份属性， -事件消费者可以使用这些属性将这个事件与其他事件相关联。 -如果此类身份属性恰好是事件“数据”的一部分， -则事件生产者还会将身份属性添加到“上下文属性”中， -以便事件消费者可以轻松访问此信息，而无需解码和检查事件数据。 -此类身份属性还可用于帮助中间网关确定如何路由事件。 - -## 事件数据 - -正如[数据](#数据)所定义的那样，CloudEvents 可以包括有关事件的特定域的信息。 -这些信息将被封装在`data`中。 - -- 描述: 事件负载。 本规范对该信息的类型不作任何限制。 - 它被编码为一种媒体格式，这种格式由`datacontenttype` 属性(如 application/json)指定， - 并在存在这些相应属性时遵循`dataschema`格式。 - It is encoded into a media format - -- 约束条件: - - 可选的 - -# 大小限制 - -在很多情况下，CloudEvents 将通过一个或多个通用中间人进行转发， -每个中间人都可能对转发事件的大小施加限制。 -CloudEvents 也可能直接被路由到消费者，如嵌入式设备， -这些设备是受存储或内存限制的，对单个大型事件表现不佳。 - -事件的“大小”是它的线路大小，包括在线路上为事件传输的每一位： -协议帧元数据、事件元数据和事件数据，基于所选的事件格式和所选的协议绑定。 - -如果应用程序配置需要跨不同协议路由事件或重新编码事件， -应用程序能使用的效率最低的协议和编码，都修腰符合这些大小限制： - -- 中间人转发的事件大小必须为 64 KB 或更小。 -- 消费者应该能接受大小至少为 64 KB 的事件。 - -为了方便，上述规则将允许生产者安全地发布最大 64KB 的事件。 -这里的安全意味着生产者期望事件被所有中间人接受并合理地转发。 -它是在任何特定消费者的控制之下，无论消费者是否由于本地考虑而选择接受或拒绝该大小的事件。 - -通常，CloudEvents 发布者应该通过避免将大型数据项嵌入到事件而使用事件有效链接到此类数据项， -来保持事件紧凑。 -从访问控制的角度来看，这种方法对更广泛的事件分布式化有帮助， -因为通过解析链接访问与事件相关的细节能实现差异化访问控制和选择性披露， -而不是将敏感详细数据直接嵌入到事件中。 - -# 隐私与安全 - -互操作性是本规范背后的主要驱动力， -实现此目标需要一些信息明确可用，这可能导致信息的泄漏。 - -考虑以下事项以防止信息意外泄漏，尤其是在利用第三方平台和通信网络时： - -- 上下文属性 - - 敏感信息不应在上下文属性中携带。 - - CloudEvent 生产者、消费者和中间人可以自查并记录下上下文属性。 - -- 数据 - - 特定的[事件数据](#事件数据) 应该被加密以限制对受信任方的可见性。 - 用于这种加密的机制是生产者和消费者之间的协议，不在本规范的讨论范围内。 - -- 协议绑定 - 应该采用协议级别的安全性机制来确保 CloudEvents 完成可信和安全的交换。 - -# 示例 - -以下示例展示了一个序列化为 JSON 的 CloudEvent： - -```JSON -{ - "specversion" : "1.0", - "type" : "com.github.pull.create", - "source" : "https://github.com/cloudevents/spec/pull", - "subject" : "123", - "id" : "A234-1234-1234", - "time" : "2018-04-05T17:31:00Z", - "comexampleextension1" : "value", - "comexampleothervalue" : 5, - "datacontenttype" : "text/xml", - "data" : "" -} -```