セル領域の更新

本インターフェースを呼び出すと、セルの値、背景色、ハイパーリンク、フォントサイズ、水平揃え、垂直揃えなど、セルの情報を更新できます。

リクエスト

基本情報

フィールド	値
HTTP URL	`https://api.dingtalk.io/v1.0/doc/workbooks/{workbookId}/sheets/{sheetId}/ranges/{rangeAddress}`
HTTP Method	PUT
対応アプリタイプ	appType-社内アプリ　appType-サードパーティ社内アプリ
必要な権限	permission-Document.Workbook.Write-スプレッドシート書き込み権限

リクエストヘッダー

名前	タイプ	必須	説明
x-acs-dingtalk-access-token	String	はい	本インターフェースを呼び出すためのアクセス認証情報です。以下の方法で取得できます： - 社内アプリの場合は、社内アプリの access token を取得インターフェースを呼び出して取得します。 - サードパーティ社内アプリの場合は、サードパーティアプリの認可企業の access token を取得インターフェースを呼び出して取得します。

パスパラメータ

名前	タイプ	必須	説明
workbookId	String	はい	スプレッドシートファイル ID です。ナレッジベース API が返す `nodeId(dentryUuid)` がスプレッドシートの `workbookId` です。ノードの取得およびナレッジベースドキュメントの作成インターフェースを呼び出して取得できます。
sheetId	String	はい	ワークシート ID または名前です。 - 社内アプリの場合は、すべてのワークシートを取得インターフェースを呼び出して id または name パラメータ値を取得できます。 - サードパーティ社内アプリの場合は、ワークシートの作成インターフェースを呼び出して id および name を取得できます。
rangeAddress	String	はい	Range アドレスです。

クエリパラメータ

名前	タイプ	必須	説明
operatorId	String	はい	操作者の unionId です。ユーザー詳細の照会インターフェースを呼び出して取得できます。操作者に権限がない場合、インターフェースは `The operator has no permission` というエラーを返します。

リクエストボディ

名前	タイプ	必須	説明
horizontalAlignments	Array of Array	いいえ	水平揃え方式。設定可能な値： ‘left’-左揃え、‘center’-中央揃え、‘right’-右揃え、‘general’-デフォルトの揃え方式。 Range アドレスの範囲に応じてパラメータを渡します。形式は二次元配列です。詳細は以下の例を参照してください： Range アドレスの範囲が何行あれば、本パラメータの二次元配列内にその数の要素が存在します。Range アドレスの範囲が何列あれば、本パラメータの二次元配列の各要素内にその数の値が存在します。例 1：Range アドレスが A1:B3、範囲内が 3 行 2 列のテーブルである場合、本パラメータ値の形式は以下のとおりです： `{ "horizontalAlignments": [ ["left", "general"], ["center", "general"], ["right", "general"] ] }` 例 2：Range アドレスが A1:C3、範囲内が 3 行 3 列のテーブルである場合、本パラメータ値の形式は以下のとおりです： `{ "horizontalAlignments": [ ["left", "left", "general"], ["center", "center", "general"], ["right", "right", "general"] ] }`
numberFormat	String	いいえ	番号フォーマット。	---	---	---	名前	番号フォーマット	例	一般	”General”	テキスト	”@“	数値	”#,##0”	1,234	数値（小数点）	”#,##0.00”	1,234.56	パーセント	”0%“	12%	パーセント（小数点）	“0.00%“	12.34%	指数	”0.00E+00”	1.01E+03	人民元	”¥#,##0”	¥1,234	人民元（小数点）	¥#,##0.00”	¥1,234.56	米ドル	”$#,##0”	$1,234	米ドル（小数点）	”$#,##0.00”	$1,234.56	日付	”yyyy/m/d”	2022/1/1	日付（中国語）	“yyyy年m月d日”	2022年1月1日	日付（中国語年月）	“yyyy年m月”	2022年1月	時刻	”hh:mm:ss”	00:00:00	日付時刻	”yyyy/m/d hh:mm:ss”	2022/1/1 00:00:00
wordWrap	String	いいえ	折り返し方式。設定可能な値： - overflow：オーバーフロー - clip：切り捨て - autoWrap：文字列の折り返し
values	Array of Array	いいえ	セルの値。Range アドレスの範囲に応じてパラメータを渡します。形式は二次元配列です。詳細は以下の例を参照してください： Range アドレスの範囲が何行あれば、本パラメータの二次元配列内にその数の要素が存在します。Range アドレスの範囲が何列あれば、本パラメータの二次元配列の各要素内にその数の値が存在します。例 1：Range アドレスが A1:B3、範囲内が 3 行 2 列のテーブルである場合、本パラメータ値の形式は以下のとおりです： `{ "values": [ ["1", "2"], ["3", "4"], ["5", "6"] ] }` 例 2：Range アドレスが A1:C3、範囲内が 3 行 3 列のテーブルである場合、本パラメータ値の形式は以下のとおりです： `{ "values": [ ["1","2","3"], ["4","5","6"], ["7","8","9"] ] }`
complexValues	Array of Array	いいえ	セルの値。Range アドレスの範囲に応じてパラメータを渡します。形式は二次元配列です。本フィールドを利用することで、対応するセルに「リッチテキスト形式」のコンテンツを入力できます。詳細は後述の付録を参照してください。
backgroundColors	Array of Array	いいえ	背景色。色の 16 進数値で指定し、Range アドレスの範囲に応じてパラメータを渡します。形式は二次元配列です。詳細は以下の例を参照してください： Range アドレスの範囲が何行あれば、本パラメータの二次元配列内にその数の要素が存在します。Range アドレスの範囲が何列あれば、本パラメータの二次元配列の各要素内にその数の値が存在します。例 1：Range アドレスが A1:B3、範囲内が 3 行 2 列のテーブルである場合、本パラメータ値の形式は以下のとおりです： `{ "backgroundColors": [ ["#ff0000", "#00ff00"], ["#f0f0f0", "#0000ff"], ["#f0f0f0", "#0000ff"] ] }` 例 2：Range アドレスが A1:C3、範囲内が 3 行 3 列のテーブルである場合、本パラメータ値の形式は以下のとおりです： `{ "backgroundColors": [ ["#ff0000","#ff0000","#ff0000"], ["#ff0000","#ff0000","#ff0000"], ["#ff0000","#ff0000","#ff0000"] ] }`
fontColors	Array of Array	いいえ	フォント色。色の 16 進数値で指定し、Range アドレスの範囲に応じてパラメータを渡します。形式は二次元配列です。
fontSizes	Array of Array	いいえ	フォントサイズ。Range アドレスの範囲に応じてパラメータを渡します。形式は二次元配列です。詳細は以下の例を参照してください： Range アドレスの範囲が何行あれば、本パラメータの二次元配列内にその数の要素が存在します。Range アドレスの範囲が何列あれば、本パラメータの二次元配列の各要素内にその数の値が存在します。例 1：Range アドレスが A1:B3、範囲内が 3 行 2 列のテーブルである場合、本パラメータ値の形式は以下のとおりです： `{ "fontSizes": [ [14, 14], [15, 15], [10, 10] ] }` 例 2：Range アドレスが A1:C3、範囲内が 3 行 3 列のテーブルである場合、本パラメータ値の形式は以下のとおりです： `{ "fontSizes": [ [14, 14, 14], [15, 15, 15], [10, 10, 10] ] }`
fontWeights	Array of Array	いいえ	フォントの太さ。設定可能な値： - bold：太字 - normal：標準
hyperlinks	Array of Array	いいえ	ハイパーリンク。Range アドレスの範囲に応じてパラメータを渡します。形式は二次元配列です。詳細は以下の例を参照してください： Range アドレスの範囲が何行あれば、本パラメータの二次元配列内にその数の要素が存在します。Range アドレスの範囲が何列あれば、本パラメータの二次元配列の各要素内にその数の値が存在します。例 1：Range アドレスが A1:B3、範囲内が 3 行 2 列のテーブルである場合、本パラメータ値の形式は以下のとおりです： { "hyperlinks": [ [ { "type": "path", "link": "https://www.dingtalk.io", "text": "test" }, { "type": "sheet", "link": "Sheet2", "text": "テスト" } ], [ { "type": "range", "link": "Sheet2!A4", "text": "test" }, { "type": "path", "link": "https://www.dingtalk.io", "text": "テスト" } ], [ { "type": "range", "link": "Sheet2!A4", "text": "2" }, { "type": "sheet", "link": "Sheet2", "text": "テスト" } ] ] } 例 2：Range アドレスが A1:C3、範囲内が 3 行 3 列のテーブルである場合、本パラメータ値の形式は以下のとおりです： { "hyperlinks": [ [ { "type": "path", "link": "https://www.dingtalk.io", "text": "test" }, { "type": "sheet", "link": "Sheet2", "text": "テスト" },{ "type": "path", "link": "https://www.dingtalk.io", "text": "test" } ], [ { "type": "range", "link": "Sheet2!A4", "text": "test" }, { "type": "path", "link": "https://www.dingtalk.io", "text": "テスト" },{ "type": "path", "link": "https://www.dingtalk.io", "text": "test" } ], [ { "type": "range", "link": "Sheet2!A4", "text": "2" }, { "type": "sheet", "link": "Sheet2", "text": "テスト" },{ "type": "path", "link": "https://www.dingtalk.io", "text": "test" } ] ] }
verticalAlignments	Array of Array	いいえ	垂直揃え方式。設定可能な値：‘top’-上揃え、‘middle’-上下中央揃え、‘bottom’-下揃え。 Range アドレスの範囲に応じてパラメータを渡します。形式は二次元配列です。詳細は以下の例を参照してください： Range アドレスの範囲が何行あれば、本パラメータの二次元配列内にその数の要素が存在します。Range アドレスの範囲が何列あれば、本パラメータの二次元配列の各要素内にその数の値が存在します。例 1：Range アドレスが A1:B3、範囲内が 3 行 2 列のテーブルである場合、本パラメータ値の形式は以下のとおりです： `{ "verticalAlignments": [ ["top", "top"], ["middle", "middle"], ["bottom", "bottom"] ] }` 例 2：Range アドレスが A1:C3、範囲内が 3 行 3 列のテーブルである場合、本パラメータ値の形式は以下のとおりです： `{ "verticalAlignments": [ ["top", "top", "top"], ["middle", "middle", "middle"], ["bottom", "bottom", "bottom"] ] }`

リクエスト例

HTTP

PUT /v1.0/doc/workbooks/e54Lqxxxxx/sheets/Sheet1/ranges/A1:B1?operatorId=ppgAQuxxxxx HTTP/1.1
Host:api.dingtalk.io
x-acs-dingtalk-access-token:f86e0bxxx
Content-Type:application/json

{
  "horizontalAlignments" : [ [ "general" ] ],
  "numberFormat" : "@",
  "wordWrap" : "autoWrap",
  "values" : [ [ "text" ] ],
  "complexValues" : [ [ "text" ] ],
  "backgroundColors" : [ [ "#ff0000" ] ],
  "fontColors" : [ [ "#000000" ] ],
  "fontSizes" : [ [ 14 ] ],
  "fontWeights" : [ [ "bold" ] ],
  "hyperlinks" : [ [ {
    "type" : "path",
    "link" : "https://www.dingtalk.io",
    "text" : "DingTalk"
  } ] ],
  "verticalAlignments" : [ [ "middle" ] ]
}

レスポンス

レスポンスボディ

名前	タイプ	説明
a1Notation	String	更新された range アドレス。

レスポンスボディ例

HTTP/1.1 200 OK
Content-Type:application/json

{
  "a1Notation" : "A1"
}

エラーコード

本インターフェースの呼び出しでエラーが発生した場合は、エラーメッセージをもとにグローバルエラーコードドキュメントで解決方法を検索してください。

HttpCode	エラーコード	エラーメッセージ	説明
400	invalidRequest.inputArgs.invalid	%s	リクエストパラメータが不正です。エラーメッセージを確認してください。
400	invalidRequest.inputArgs.workbookIdIllegal	The workbookId is illegal.	workbookId が不正です。
400	invalidRequest.resource.notWorkbook	%s	サポートされていないドキュメントタイプです。workbookId を確認してください。
403	forbidden.accessDenied	The operator has no permission.	現在のユーザーには本操作の権限がありません。
403	forbidden.acrossOrg	%s	リクエストが不正です。アクセスするドキュメントが access token で指定された組織に所属しているかを確認してください。
403	forbidden.operationIllegal	%s	リクエスト操作が不正です。エラーメッセージを確認してください。
403	forbidden.document.sizeOverLimit	The document size is over limit and the server is unable to complete your request. Retry is unlikely to work unless the document size is decreased.	スプレッドシートのコンテンツが大きすぎます。コンテンツを縮小してください。
404	invalidRequest.resource.notFound	%s	リクエストに失敗しました。アクセスするリソースが見つかりません。
500	serviceBusy	The server is busy and unable to complete your request. Please try again later.	サービスがビジー状態です。後で再試行してください。
500	internalError	The server encountered an internal error and was unable to complete your request. Please try again later.	サーバー内部エラーです。後で再試行してください。

API 呼び出しガイド

認証と認可

連絡先

カレンダー

会議

AI Table

Docs とファイル

IM

リクエスト

基本情報

リクエストヘッダー

パスパラメータ

クエリパラメータ

リクエストボディ

リクエスト例

レスポンス

レスポンスボディ

レスポンスボディ例

エラーコード

​リクエスト

​基本情報

​リクエストヘッダー

​パスパラメータ

​クエリパラメータ

​リクエストボディ

​リクエスト例

​レスポンス

​レスポンスボディ

​レスポンスボディ例

​エラーコード

リクエスト

基本情報

リクエストヘッダー

パスパラメータ

クエリパラメータ

リクエストボディ

リクエスト例

レスポンス

レスポンスボディ

レスポンスボディ例

エラーコード