AIP-133 标准方法:Create

编号133
原文链接AIP-133: Standard methods: Create
状态批准
创建日期2019-01-23
更新日期2019-01-23

在REST API中,通常向集合URI(如 /v1/publishers/{publisher}/books )发出POST请求,在集合中创建新资源。

面向资源设计(AIP-121)提供Create方法,遵循这一模式。这些接口接受上级集合和欲创建资源(可能还有其他参数),返回新建的资源。

指南

API通常 应当 为资源提供Create方法,除非这个操作对用户没有意义。Create方法的目的是在现有集合中创建新资源。

Create方法使用以下模式指定:

rpc CreateBook(CreateBookRequest) returns (Book) {option (google.api.http) = {post: "/v1/{parent=publishers/*}/books"body: "book"};option (google.api.method_signature) = "parent,book";
}
  • 接口的名字 必须 以单词Create开头,其余部分 应当 是目标资源的单数形式。
  • 请求消息 必须 与接口名字一致,并带有 Request 后缀。
  • 应答消息 必须 是资源本身。不存在 CreateBookResponse
    • 应答 应当 包括完整资源数据, 必须 包括所有支持的域,仅输入域除外(参考AIP-203)。
    • 如果Create接口是长运行创建,应答消息 必须 是解析为资源本身的 google.longrunning.Operation
  • HTTP动词必须是 POST
  • 添加新资源的集合 应当 映射到URI路径。
    • 集合的上级资源 应当 称为 parent应当 是URI路径中唯一的变量。
    • 集合标识符(例子中的 books必须 是字面值字符串。
  • google.api.http 注解中 必须 包含 body 键, 必须 映射到请求消息中的资源域。
    • 所有其他域 应当 映射到URI查询参数。
  • 应当 存在一个 google.api.method_signature 注解,值为 "parent,{resource},{resource}_id" 。如果不需要资源I标识,值为 "parent,{resource}"
  • 如果API在[BROKEN LINK: 管理平面]上运行,则操作应具有[BROKEN LINK: 强一致性]:创建操作的完成必须意味着所有用户可设置的值和资源的存在已达到稳定状态,并且读取资源状态返回一致的应答。

请求消息

创建方法实现了一个常见的请求消息模式:

```proto message CreateBookRequest { / 将在其中创建此书籍的上级资源。 / 格式:publishers/{publisher} string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { child_type: “library.googleapis.com/Book” }];

/ 用于书籍的ID,将成为书籍资源名字的最终组成部分。 / / 此值应为4-63个字符,有效字符为[a-z][0-9]-/。 string book_id = 2 [(google.api.field_behavior) = REQUIRED];

// 要创建的书籍。 Book book = 3 [(google.api.field_behavior) = REQUIRED]; } ```

  • 必须包含一个parent域,除非正在创建的资源是顶级资源。它应称为parent。
    • 该域应被注释为必需([BROKEN LINK: AIP-203])。
    • 该域必须标识正在创建的资源的[BROKEN LINK: 资源类型]([BROKEN LINK: AIP-123])。
  • 对于管理平面资源,必须包含{resource}_id域,对于数据平面资源,应包含该域。
  • 必须包含资源域,并且必须映射到POST主体。
  • 请求消息不得包含任何其他必需域,并且不应包含其他可选域,除非在此或另一个AIP中描述。

长运行创建

某些资源创建资源所需的时间比常规API请求合理的时间长。在这种情况下,API应使用长运行操作([BROKEN LINK: AIP-151]):

```proto rpc CreateBook(CreateBookRequest) returns (google.longrunning.Operation) { option (google.api.http) = { post: “/v1/{parent=publishers/*}/books” body: “book” }; option (google.longrunning.operation_info) = { response_type: “Book” metadata_type: “OperationMetadata” }; } ```

  • 应答类型必须设置为资源(如果接口不是长运行,则返回类型将是该资源)。
  • 必须指定response_type和metadata_type域。

重要提示: 声明友好资源([BROKEN LINK: AIP-128])应使用长运行操作。如果请求实际上是立即的,则服务可以返回已设置为完成的LRO。

用户指定的ID

如果API在[BROKEN LINK: 管理平面]上运行,则API必须允许用户在创建时指定资源的ID组件(资源名字的最后一段)。

在[BROKEN LINK: 数据平面]上,API应允许用户指定ID。特殊情况应具有以下行为:

  • 数据平面资源允许相同的记录,无需区分两者(例如,没有主键的表中的行)。
  • 数据平面资源不会在[BROKEN LINK: 声明客户端]中公开。

API可以允许{resource}_id域具有[BROKEN LINK: field_behavior] OPTIONAL,并在未指定时生成系统生成的ID。

例如:

``` // 使用用户指定的ID。 publishers/lacroix/books/les-miserables

// 使用系统生成的ID。 publishers/012345678-abcd-cdef/books/12341234-5678-abcd ```

  • {resource}_id域必须存在于请求消息上,而不是资源本身。
    • 该域可以是必需的或可选的。如果它是必需的,则应包括相应的注释。
  • 必须忽略资源上的name域。
  • 接口上应恰好有一个google.api.method_signature注释,如果正在创建的资源不是顶级资源,则其值为"parent,{resource},{resource}_id",如果正在创建的资源是顶级资源,则其值为"{resource},{resource}_id"。
  • 文档应解释可接受的格式是什么,并且格式应遵循[BROKEN LINK: AIP-122]中资源名字格式的指南。
  • 如果用户尝试创建具有会导致重复资源名字的ID的资源,则服务必须返回ALREADY_EXISTS错误。
    • 但是,如果进行调用的用户没有权限查看重复资源,则服务必须返回PERMISSION_DENIED错误。

注意: 对于REST API,用户指定的ID域{resource}_id作为请求URI上的查询参数提供。

错误

参考错误,特别是[BROKEN LINK: 何时使用PERMISSION_DENIED和NOT_FOUND错误]。

进一步阅读

  • 有关在Create方法中确保幂等性,请参考[BROKEN LINK: AIP-155]。
  • 有关涉及Unicode的资源命名,请参考[BROKEN LINK: AIP-210]。

理由

要求用户指定的ID

[BROKEN LINK: 声明客户端]使用资源ID作为应用更新和冲突解决的一种方式。缺少用户指定的ID意味着客户端无法找到资源,除非他们在本地存储标识符,并且可能导致重新创建资源。这反过来又对所有引用它的资源产生下游影响,迫使它们更新到新创建资源的ID。

拥有用户指定的ID还意味着客户端可以预先计算资源名字并在其他资源的引用中使用它。

修订记录

  • 2023-10-20 澄清{resource}_id仅对管理平面资源是必需的。
  • 2023-08-24 添加一致性要求。
  • 2023-05-11 更改关于resource_id的指南为必须。
  • 2022-11-04 引用AIP-193中的聚合错误指南,类似于其他CRUDL AIP。
  • 2022-06-02 更改后缀描述以消除多余的“-”。
  • 2020-10-06 添加声明友好指南。
  • 2020-08-14 更新错误指南以使用permission denied而不是forbidden。
  • 2020-06-08 添加关于返回完整资源的指南。
  • 2019-11-22 添加关于发送重复名字时使用何种错误的澄清。
  • 2019-10-18 添加关于注释的指南。
  • 2019-08-01 将示例从“shelves”更改为“publishers”,以提供更好的资源所有权示例。
  • 2019-06-10 添加长运行创建的指南。
  • 2019-05-29 添加对标准方法中任意域的明确禁止。

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

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

相关文章

HarmonyOS简介:HarmonyOS核心技术理念

核心理念 一次开发、多端部署可分可合、自由流转统一生态、原生智能 一次开发、多端部署 可分可合 自由流转 自由流转可分为跨端迁移和多端协同两种情况 统一生态 支持业界主流跨平台开发框架,通过多层次的开放能力提供统一接入标准,实现三方框架快速…

ES6语法

一、Let、const、var变量定义 1.let 声明的变量有严格局部作用域 <!DOCTYPE html> <html lang"en"> <head><meta charset"UTF-8"><meta name"viewport" content"widthdevice-width, initial-scale1.0"&g…

书生大模型实战营3

文章目录 L0——入门岛git基础Git 是什么&#xff1f;Git 中的一些基本概念工作区、暂存区和 Git 仓库区文件状态分支主要功能 Git 平台介绍GitHubGitLabGitee Git 下载配置验证下载 Git配置 Git验证 Git配置 Git常用操作Git简易入门四部曲Git其他指令 闯关任务任务1: 破冰活动…

前端——js高级25.1.27

复习&#xff1a;对象 问题一&#xff1a; 多个数据的封装提 一个对象对应现实中的一个事物 问题二&#xff1a; 统一管理多个数据 问题三&#xff1a; 属性&#xff1a;组成&#xff1a;属性名属性值 &#xff08;属性名为字符串&#xff0c;属性值任意&#xff09; 方…

[创业之路-270]:《向流程设计要效率》-2-企业流程架构模式 POS架构(规划、业务运营、支撑)、OES架构(业务运营、使能、支撑)

目录 一、POS架构 二、OES架构 三、POS架构与OES架构的差异 四、各自的典型示例 POS架构典型示例 OES架构典型示例 示例分析 五、各自的典型企业 POS架构典型企业 OES架构典型企业 分析 六、各自典型的流程 POS架构的典型流程 OES架构的典型流程 企业流程架构模式…

计算机的错误计算(二百二十二)

摘要 利用大模型化简计算 实验表明&#xff0c;虽然结果正确&#xff0c;但是&#xff0c;大模型既绕了弯路&#xff0c;又有数值计算错误。 与前面相同&#xff0c;再利用同一个算式看看另外一个大模型的化简与计算能力。 例1. 化简计算摘要中算式。 下面是与一个大模型的…

【现代深度学习技术】深度学习计算 | 参数管理

【作者主页】Francek Chen 【专栏介绍】 ⌈ ⌈ ⌈PyTorch深度学习 ⌋ ⌋ ⌋ 深度学习 (DL, Deep Learning) 特指基于深层神经网络模型和方法的机器学习。它是在统计机器学习、人工神经网络等算法模型基础上&#xff0c;结合当代大数据和大算力的发展而发展出来的。深度学习最重…

C语言,无法正常释放char*的空间

问题描述 #include <stdio.h> #include <stdio.h>const int STRSIZR 10;int main() {char *str (char *)malloc(STRSIZR*sizeof(char));str "string";printf("%s\n", str);free(str); } 乍一看&#xff0c;这块代码没有什么问题。直接书写…

【开源免费】基于Vue和SpringBoot的在线文档管理系统(附论文)

本文项目编号 T 038 &#xff0c;文末自助获取源码 \color{red}{T038&#xff0c;文末自助获取源码} T038&#xff0c;文末自助获取源码 目录 一、系统介绍二、演示录屏三、启动教程四、功能截图五、文案资料5.1 选题背景5.2 国内外研究现状5.3 可行性分析 六、核心代码6.1 查…

忘记宝塔的访问地址怎么找

在linux中安装宝塔面板后会生成网址、账号和密码 如果网址忘记了那将进不去宝塔面板该怎么办呢&#xff1f; bt命令 我们输入 bt 命令的时候&#xff0c;是在根目录里面进行操作的。 / bt 我们根据自己的需要&#xff0c;选择对应的数字就可以了。 bt 14 输入 14 查看面板默…

力扣hot100-->滑动窗口、贪心

你好呀&#xff0c;欢迎来到 Dong雨 的技术小栈 &#x1f331; 在这里&#xff0c;我们一同探索代码的奥秘&#xff0c;感受技术的魅力 ✨。 &#x1f449; 我的小世界&#xff1a;Dong雨 &#x1f4cc; 分享我的学习旅程 &#x1f6e0;️ 提供贴心的实用工具 &#x1f4a1; 记…

【蓝桥杯嵌入式入门与进阶】2.与开发板之间破冰:初始开发板和原理图2

个人主页&#xff1a;Icomi 专栏地址&#xff1a;蓝桥杯嵌入式组入门与进阶 大家好&#xff0c;我是一颗米&#xff0c;本篇专栏旨在帮助大家从0开始入门蓝桥杯并且进阶&#xff0c;若对本系列文章感兴趣&#xff0c;欢迎订阅我的专栏&#xff0c;我将持续更新&#xff0c;祝你…

Spring Boot - 数据库集成02 - 集成JPA

集成JPA 文章目录 集成JPA一&#xff1a;JPA概述1&#xff1a;JPA & JDBC2&#xff1a;JPA规范3&#xff1a;JPA的状态和转换关系 二&#xff1a;Spring data JPA1&#xff1a;JPA_repository1.1&#xff1a;CurdRepostory<T, ID>1.2&#xff1a;PagingAndSortingRep…

从ai产品推荐到利用cursor快速掌握一个开源项目再到langchain手搓一个Text2Sql agent

目录 0. 经验分享&#xff1a;产品推荐 1. 经验分享&#xff1a;提示词优化 2. 经验分享&#xff1a;使用cursor 阅读一篇文章 3. 经验分享&#xff1a;使用cursor 阅读一个完全陌生的开源项目 4. 经验分享&#xff1a;手搓一个text2sql agent &#xff08;使用langchain l…

【Java-数据结构】Java 链表面试题下 “最后一公里”:解决复杂链表问题的致胜法宝

我的个人主页 我的专栏&#xff1a;Java-数据结构&#xff0c;希望能帮助到大家&#xff01;&#xff01;&#xff01;点赞❤ 收藏❤ 引言&#xff1a; Java链表&#xff0c;看似简单的链式结构&#xff0c;却蕴含着诸多有趣的特性与奥秘&#xff0c;等待我们去挖掘。它就像一…

智慧园区系统的类型及其在企业管理效率提升中的关键作用解析

内容概要 在智慧园区的建设中&#xff0c;各类系统的采用是提升管理效率的关键所在。快鲸智慧园区(楼宇)管理系统&#xff0c;通过其全面数字化的管理手段&#xff0c;已经成为了企业管理的新标杆。这一系统能够有效整合租赁管理、资产管理、招商管理和物业管理等功能&#xf…

多级缓存(亿级并发解决方案)

多级缓存&#xff08;亿级流量&#xff08;并发&#xff09;的缓存方案&#xff09; 传统缓存的问题 传统缓存是请求到达tomcat后&#xff0c;先查询redis&#xff0c;如果未命中则查询数据库&#xff0c;问题如下&#xff1a; &#xff08;1&#xff09;请求要经过tomcat处…

第27篇 基于ARM A9处理器用C语言实现中断<三>

Q&#xff1a;基于ARM A9处理器怎样设计C语言工程&#xff0c;同时使用按键中断和定时器中断在红色LED上计数&#xff1f; A&#xff1a;基本原理&#xff1a;设置HPS Timer 0和按键中断源&#xff0c;主程序调用set_A9_IRQ_stack( )函数设置中断模式的ARM堆栈指针&#xff0c…

C++ 中用于控制输出格式的操纵符——setw 、setfill、setprecision、fixed

目录 四种操纵符简要介绍 setprecision基本用法 setfill的基本用法 fixed的基本用法 setw基本用法 以下是一些常见的用法和示例&#xff1a; 1. 设置字段宽度和填充字符 2. 设置字段宽度和对齐方式 3. 设置字段宽度和精度 4. 设置字段宽度和填充字符&#xff0c;结合…

【1.安装ubuntu22.04】

目录 参考文章链接电脑参数安装过程准备查看/更改引导方式查看/更改磁盘的分区格式关闭BitLocker加密压缩分区关闭独显直连制作Ubuntu安装盘下载镜像制作启动盘 进入BIOS模式进行设置Secure Boot引导项顺序try or install ubuntu 进入安装分区启动引导器个人信息和重启 参考文章…