AIP-127 HTTP和gRPC转码

编号127
原文链接AIP-127: HTTP and gRPC Transcoding
状态批准
创建日期2019-08-22
更新日期2019-08-22

遵守面向资源设计的API使用RPC进行定义,但面向资源设计框架允许这些API表现为整体上符合REST/JSON约定的接口。这一点很重要,可以帮助开发者利用现有知识:超过80%的公开API遵守REST约定,开发者已经习惯了这种模式。

指南

API 必须 每个RPC提供HTTP定义,双向流式RPC除外。因为HTTP/1.1无法原生支持双向流式传输。提供双向流式方法的API 应该 提供一个不依赖双向流式传输的备选方法。

HTTP方法和路径

使用protobuf时,每个RPC 必须 使用 google.api.http 注解定义HTTP方法和路径:

rpc CreateBook(CreateBookRequest) returns (Book) {option (google.api.http) = {post: "/v1/{parent=publishers/*}/books"body: "book"};
}message CreateBookRequest {// The publisher who will publish this book.// When using HTTP/JSON, this field is automatically populated based// on the URI, because of the `{parent=publishers/*}` syntax.string parent = 1 [(google.api.field_behavior) = REQUIRED,(google.api.resource_reference) = {child_type: "library.googleapis.com/Book"}];// The book to create.// When using HTTP/JSON, this field is populated based on the HTTP body,// because of the `body: "book"` syntax.Book book = 2 [(google.api.field_behavior) = REQUIRED];// The user-specified ID for the book.// When using HTTP/JSON, this field is populated based on a query string// argument, such as `?bookId=foo`. This is the fallback for fields that// are not included in either the URI or the body.// Note that clients use camelCase format to communicate the field names// to the service.string book_id = 3;
}
  • 第一个键(例子中的 post )对应于HTTP方法。RPC 可以 使用 getpostpatchdelete 方法。
    • RPC 必须 对标准方法使用规范HTTP动词,如AIP-131、AIP-132、AIP-133、AIP-134和AIP-135中讨论的那样。
    • RPC 应该 对自定义方法使用规范HTTP动词,如AIP-136中讨论的那样。
    • RPC 不应该 使用 putcustom
  • 表示URI的值。
    • URI 必须 使用 {foo=bar/*} 语法表示应在请求proto中填充的变量。当捕获资源名字时,变量 必须 包括完整的资源名字,而非仅仅是标识部分。
    • URI 可以 使用嵌套域作为变量名。(还有,AIP-134要求 Update 请求必须这么做。)
    • URI 必须 使用 * 字符来表示标识部分,它匹配除 / 之外的所有URI安全字符。如果需要匹配字符 / ,URI 可以 使用 ** 作为URI的最后一段。
  • body 键定义了请求中将作为HTTP主体发送的单一顶层域。如果主体是 *,表示请求对象自身是HTTP主体。请求主体按照protobuf规范JSON编码生成JSON。
    • 使用 GETDELETE HTTP动词的RPC 不得 定义 body
    • 创建(AIP-133)和更新(AIP-134)请求 必须 使用规定的 body
    • 自定义方法(AIP-136) 应该 使用规定的 body
    • body 不得 包含嵌套域(或使用 . 字符)。
    • body 不得 与URI参数相同。
    • body 不得repeated 域。
    • 不应 使用 json_name 注解改变JSON中的域名字,除非需要向后兼容。

注意: 双向流式RPC不应该包含任何 google.api.http 注解。如果可以,服务 应该 提供等效的非流式RPC。

多URI绑定

有时一个RPC需要对应多个URI:

rpc CreateBook(CreateBookRequest) returns (Book) {option (google.api.http) = {post: "/v1/{parent=publishers/*}/books"body: "book"additional_bindings: {post: "/v1/{parent=authors/*}/books"body: "book"}additional_bindings: {post: "/v1/books"body: "book"}};
}
  • RPC 可以 定义任意数量的附加绑定。附加绑定结构与 google.api.http 注解相同(实际上这是一个递归引用)。
  • RPC 不得 在附加绑定中嵌套定义附加绑定。
  • body 子句 必须 在顶级注解和每个附加绑定中相同。

修订记录

  • 2022-08-18 :添加要求查询字符串参数名字使用camelCase格式的注释。
  • 2021-01-06 :添加对 body 和嵌套域的明确描述。
  • 2019-09-23 :添加关于请求主体编码的陈述,和避免使用 json_name 的指南。

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/diannao/67944.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

WPF基础 | 初探 WPF:理解其核心架构与开发环境搭建

WPF基础 | 初探 WPF:理解其核心架构与开发环境搭建 一、前言二、WPF 核心架构2.1 核心组件2.2 布局系统2.3 数据绑定机制2.4 事件处理机制 三、WPF 开发环境搭建3.1 安装 Visual Studio3.2 创建第一个 WPF 应用程序 结束语优质源码分享 WPF基础 | 初探 WPF&#xff…

字节跳动自研HTTP开源框架Hertz简介附使用示例

字节跳动自研 HTTP 框架 Hertz Hertz 是字节跳动自研的高性能 HTTP 框架,专为高并发、低延迟的场景设计。它基于 Go 语言开发,结合了字节跳动在微服务架构中的实践经验,旨在提供更高效的 HTTP 服务开发体验。 1. 背景介绍 随着字节跳动业务…

实战演示:利用ChatGPT高效撰写论文

在当今学术界,撰写论文是一项必不可少的技能。然而,许多研究人员和学生在写作过程中常常感到困惑和压力。幸运的是,人工智能的快速发展为我们提供了新的工具,其中ChatGPT便是一个优秀的选择。本文将通过易创AI创作平台&#xff0c…

在线可编辑Excel

1. Handsontable 特点: 提供了类似 Excel 的表格编辑体验,包括单元格样式、公式计算、数据验证等功能。 支持多种插件,如筛选、排序、合并单元格等。 轻量级且易于集成到现有项目中。 具备强大的自定义能力,可以调整外观和行为…

Vue.js 渐进式增强:如何逐步为传统项目注入活力

Vue.js 是一个渐进式框架,这意味着你可以将它逐步引入到现有项目中,而无需彻底重构。渐进式增强特别适合那些已经在使用传统服务器渲染框架(如 PHP、Django、Laravel)的项目,为它们增加动态交互功能。本篇教程将介绍如…

重构(4)

(一)添加解释性变量,使得代码更容易理解,更容易调试,也可以方便功能复用 解释性的变量 总价格为商品总价(单价*数量)-折扣(超过100个以上的打9折)邮费(原价的…

某金融科技公司内腾讯专有云企业版TCE结合宁盾2FA双因子认证满足商用密码应用安全性评估

项目背景 金融行业数据安全至关重要,涉及国家经济安全和公民个人信息安全。监管机构为了确保金融体系的安全稳定,对金融机构的密码应用提出了严格要求。例如,国务院办公厅早在 2014 年发布的《金融领域密码应用指导意见》明确指出&#xff0c…

Seata进阶全文详解(集成Nacos及SpringCloud配置)

Seata 简介 在当今微服务架构盛行的时代,分布式系统中的事务管理成为了一个极具挑战性的问题。Seata(Simple Extensible Autonomous Transaction Architecture)应运而生,它是一款专为微服务架构设计的分布式事务解决方案&#xf…

spring-springboot -springcloud

目录 spring: 动态代理: spring的生命周期(bean的生命周期): SpringMvc的生命周期: SpringBoot: 自动装配: 自动装配流程: Spring中常用的注解: Spring Boot中常用的注解: SpringCloud: 1. 注册中心: 2. gateway(网关): 3. Ribbon(负载均…

STM32更新程序OTA

STM32的OTA(Over-The-Air)更新程序是一种通过无线通信方式,为设备分发新软件、配置甚至更新加密密钥的技术。以下是关于STM32 OTA更新程序的详细介绍: 一、OTA升级流程 STM32的OTA升级流程通常包括以下几个关键步骤:…

DAY9,递归实现计算 :1 + 1/3 - 1/5 + 1/7 - 1/9 + .... 1/n 的值

题目 用递归实现计算 :1 1/3 - 1/5 1/7 - 1/9 .... 1/n 的值,n通过键盘输入 思路 递进阶段:n、...... 、9、7、5、3、1 函数出口:递进到1 开始返回;函数返回值视为“总和” 回归阶段:对当前n取倒数;“总…

Formality:不可读(unread)的概念

相关阅读 Formalityhttps://blog.csdn.net/weixin_45791458/category_12841971.html?spm1001.2014.3001.5482https://blog.csdn.net/weixin_45791458/category_12841971.html?spm1001.2014.3001.5482 在Formality中有时会遇到不可读(unread)这个概念,本文就将对此…

【27】Word:徐雅雯-艺术史文章❗

目录 题目​ NO1.2 NO3 NO4 NO5 NO6.7 NO8.9 NO10.11 注意:修改样式的字体颜色/字号,若中英文一致,选择所有脚本。格式相似的文本→检查多选/漏选格式刷F4重复上一步操作请❗每一步检查和保存 题目 NO1.2 F12另存为布局→行号布局…

关于ARM和汇编语言

一图流 ARM 计算机组成 输入设备 输出设备 存储设备 运算器 控制器 处理器读取内存程序执行的过程 取指阶段:控制器器通过地址总线向存储器发送想要获取的指令的地址编号,存储器将指定的指令发送给处理器 译码阶段:控制器对指令进行分…

Ubuntu20.04 文件系统打不开

问题描述: 电脑中安装了相关的工具, 删除了一些东西之后,Linux 电脑操作系统为 Ubuntu20.04突然打不开文件系统了,命令 sudo nautilus 可以正常进入, 显示了很多权限问题。 使用过: killall nautilus 不起作用,后查原因:我无法作为普通用户…

oneplus3t-lineage-14编译-android7

lineageOS-14.1-oneplus3t-build.md lineageOS-14(android7)的开发者模式/usb调试(adb)有root功能, 而lineageOS-16(android9)无 oneplus3t-lineage-14编译-android7 1 清华linageos镜像 x lineage-14.1-20180223-nightly-oneplus3-signed.zip ntfs分区挂载为普通用户目录…

PyTorch使用教程(9)-使用profiler进行模型性能分析

1、简介 PyTorch Profiler是一个内置的性能分析工具,可以帮助开发者定位计算资源(如CPU、GPU)的瓶颈,从而更好地优化PyTorch程序。通过捕获和分析GPU的计算、内存和带宽利用情况,能够有效识别并解决性能瓶颈。 2、原…

2025-01-22 Unity Editor 1 —— MenuItem 入门

文章目录 1 Editor 文件夹2 MenuItem3 使用示例3.1 打开网址3.2 打开文件夹3.3 Menu Toggle3.4 Menu 代码复用3.5 MenuItem 激活与失活4 代码示例 1 Editor 文件夹 ​ Editor 文件夹是 Unity 中的特殊文件夹,Unity 中所有编辑器相关的脚本都需要放置在其中&#xf…

docker 安装 mysql 详解

在平常的开发工作中,我们经常需要用到 mysql 数据库。那么在docker容器中,应该怎么安装mysql数据库呢。简单来说,第一步:拉取镜像;第二步:创建挂载目录并设置 my.conf;第三步:启动容…

linux-samba服务配置与应用

1.了解samba的配置文件 2.熟悉samba服务的实例 以前我们在windows上共享文件的话,只需右击要共享的文件夹,然后选择共享相关的选项设置即可,然后如何实现windows和linux的文件共享呢,这就涉及到了samba服务,这个软件…