创建浮动图片

在电子表格工作表的指定位置创建一张浮动图片。

前提条件

你已调用上传素材或分片上传素材上传图片至表格并获取了图片的 file_token，作为本接口中图片的 float_image_token。

使用限制

• 图片大小不得超过 20 MB。
• 单个电子表格最多支持放置 4,000 张不同 token 的图片，即表格内不重复的图片（包括浮动图片和单元格图片）总数不超过 4,000 张。将相同 token 的图片多次放置在表格的不同位置，数量上仅算一张图片。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/sheets/v3/spreadsheets/:spreadsheet_token/sheets/:sheet_id/float_images
HTTP Method	POST
接口频率限制	100 次/分钟
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可	drive:drive 查看、评论、编辑和管理云空间中所有文件 sheets:spreadsheet 查看、评论、编辑和管理电子表格 sheets:spreadsheet:write_only 编辑电子表格

请求头

名称	类型	必填	描述
Authorization	string	是	tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Type	string	是	固定值："application/json; charset=utf-8"

路径参数

名称	类型	描述
spreadsheet_token	string	电子表格的 token。可通过以下两种方式获取。了解更多，参考电子表格概述。 - 电子表格的 URL：https://sample.feishu.cn/sheets/==Iow7sNNEphp3WbtnbCscPqabcef== - 调用获取文件夹中的文件清单 示例值："Iow7sNNEphp3WbtnbCscPqabcef"
sheet_id	string	电子表格工作表的 ID。调用获取工作表获取 ID。 示例值："0beg12"

请求体

名称	类型	必填	描述
float_image_id	string	否	工作表内浮动图片的唯一标识。可不传由系统自动生成，也可选择自定义。 数据校验规则： 长度为 10，由 0-9、a-z、A-Z 组合而成。 示例值："ye06SS14ph"
float_image_token	string	否	浮动图片的 token。通过上传素材或分片上传素材上传图片至表格，获得素材的 file_token，即为 float_image_token。 注意： 该参数必填，请忽略左侧必填列的”否”。 示例值："boxcnrHpsg1QDqXAAAyachabcef"
range	string	否	浮动图片左上角所在单元格位置，只允许单个单元格的形式，如 "ahgsch!A1:A1"。了解更多，参考浮动图片使用指南。 注意： 该参数必填，请忽略左侧必填列的”否”。 示例值："ahgsch!A1:A1"
width	number(float)	否	浮动图片的宽度，单位为像素。不传会默认采用图片实际宽度，如果传则需要大于等于 20 像素。了解更多，参考浮动图片使用指南。 示例值：100
height	number(float)	否	浮动图片的高度，单位为像素。不传会默认采用图片实际高度，如果传则需要大于等于 20 像素。了解更多，参考浮动图片使用指南。 示例值：100
offset_x	number(float)	否	浮动图片左上角距离所在单元格左上角的横向偏移，单位为像素，默认为 0，设置的值需要大于等于 0、小于浮动图片左上角所在单元格的宽度。了解更多，参考浮动图片使用指南。 示例值：0
offset_y	number(float)	否	浮动图片左上角距离所在单元格左上角的纵向偏移，单位为像素，默认为 0。设置的值需要大于等于 0、小于浮动图片左上角所在单元格的高度。了解更多，参考浮动图片使用指南。 示例值：0

请求体示例

{
    "float_image_id": "ye06SS14ph",
    "float_image_token": "boxcnrHpsg1QDqXAAAyachabcef",
    "range": "ahgsch!A1:A1",
    "width": 100,
    "height": 100,
    "offset_x": 0,
    "offset_y": 0
}

cURL 请求示例

curl --location --request POST 'https://open.feishu.cn/open-apis/sheets/v3/spreadsheets/shtbchuIXPxjaYxsZzQxBqxxxxx/sheets/ea131a/float_images' \
--header 'Authorization: Bearer t-f148d9ee6b5c07373a2671e795e9e855a6f171f6' \
--header 'Content-Type: application/json' \
--data-raw '{
    "float_image_id": "ye06SS14p9",
   "float_image_token": "boxbcbQEhbFAe0XJvGzkD165FGb",
    "offset_x": 0,
    "offset_y": 0,
    "range": "ea131a!C3:C3"
}'

响应

响应体

名称	类型	描述
code	int	错误码，非 0 表示失败
msg	string	错误描述
data	\-	-
└ float_image	float_image	浮动图片的相关参数
└ float_image_id	string	浮动图片的唯一标识。用于对图片进行增删改查操作。
└ float_image_token	string	浮动图片的 token，用于图片的上传和下载操作。你可通过该 token，调用下载素材接口下载图片。
└ range	string	浮动图片左上角所在单元格位置
└ width	number(float)	浮动图片的宽度，单位为像素。
└ height	number(float)	浮动图片的高度，单位为像素。
└ offset_x	number(float)	浮动图片左上角距离所在单元格左上角的横向偏移，单位为像素。
└ offset_y	number(float)	浮动图片左上角距离所在单元格左上角的纵向偏移，单位为像素。

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "float_image": {
            "float_image_id": "ye06SS14ph",
            "float_image_token": "boxbcbQsaSqIXsxxxxx1HCPJFbh",
            "range": "ahgsch!A1:A1",
            "width": 100,
            "height": 100,
            "offset_x": 0,
            "offset_y": 0
        }
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	1310229	Wrong URL Param	检查 URL 中的路径参数是否填写正确
400	1310217	Too Many Request	请求发送过于频繁，请稍后重试
400	1310235	Retry Later	稍后重试
500	1315201	Server Error	服务内部错误，请l联系技术支持
400	1310214	SpreadSheet Not Found	电子表格 token 不存在。请检查表格 token 是否填写
400	1310213	Permission Fail	没有文档权限。参考云文档常见问题问题 3 开通文档权限
400	1310215	Sheet Id Not Found	工作表 ID 不存在。请检查工作表 ID 是否填写
400	1310202	Wrong Range	range 参数填写错误。请检查 range 参数
400	1310245	Wrong Float Image Token	浮动图片 token 填写错误。请检查 float_image_token 参数
400	1310244	Exist Float Image Id	浮动图片 ID 已存在，请重新自定义 float_image_id 参数
400	1310243	Wrong Float Image Id	浮动图片 ID 错误，请确保 float_image_id 参数字符长度为 10，且由 0-9、a-z、A-Z 组合而成
400	1310211	Wrong Sheet Id	电子表格工作表的 ID 错误。请检查工作表的 ID
400	1310247	Image Excess	图片总数超出限制。单个电子表格最多支持放置 4,000 张不同 token 的图片，即表格内不重复的图片（包括浮动图片和单元格图片）总数不超过 4,000 张
400	1310246	Wrong Float Image Value	图片宽高或者偏移参数错误。请检查 width、height、offset_x 和 offset_y 参数填写是否正确
400	1310218	Locked Cell	range 参数对应的单元格位置为保护范围。你可调用删除保护范围接口为该单元格删除保护范围或重新设置 range 参数
400	1310226	Excess Limit	超出限制，参考响应体中的错误提示
400	1310242	In Mix state	当前表格数据位于用户机房，正在将数据恢复到 SaaS 环境中，请稍后重试
500	1315203	Server Error	服务内部错误，请l联系技术支持
400	1310249	Spreadsheet Deleted	电子表格被删除，请恢复表格后重试