API call description
The API call steps are as follows: Step 1: Call the Obtain file upload information API to obtain the information required for uploading the file. Step 2: Upload the file by using the OSS header sign request method. Refer to the following examples: JavaNotes
- When the storage space type is USER, all users with permissions on the space have operation rights. Other employees must call the Add permissions API to grant authorization.
- When the storage space type is APP, any operator must call the Add permissions API to grant authorization.
request
Basic information
| Field | Value |
|---|---|
| HTTP URL | https://api.dingtalk.io/v2.0/storage/spaces/files/{parentDentryUuid}/commit |
| HTTP Method | POST |
| Supported app types | appType-Internal app appType-Third-party enterprise app |
| Permission requirements | permission-Storage.File.Write-Organization storage file write permission |
request header
| Name | Type | Required | Description |
|---|---|---|---|
| x-acs-dingtalk-access-token | String | Yes | The access credential for calling this API. Obtain it as follows: - For an internal app, call the Obtain the access token of an internal app API. - For a third-party enterprise app, call the Obtain the access token of an authorized enterprise of a third-party app API. |
path parameter
| Name | Type | Required | Description |
|---|---|---|---|
| parentDentryUuid | String | Yes | The dentryUuid of the parent node. Call the File Search or Get dentryUuid information API to obtain the dentryUuid field from the response. For the space root directory, pass the dentryUuid of the space root directory. |
query parameter
| Name | Type | Required | Description |
|---|---|---|---|
| unionId | String | Yes | The unionId of the user. Call the Query user details API to obtain it. |
request body
| Name | Type | Required | Description | |
|---|---|---|---|---|
| uploadKey | String | Yes | The unique identifier of the file to add. Call the Obtain file upload information API to obtain the value of the uploadKey parameter. | |
| name | String | Yes | The file name, including the extension. Naming rules:- No leading or trailing spaces; otherwise they are automatically trimmed. - No special characters, including tab, *, ", <, >, ` | . - Must not end with .`. |
| option | Object | No | Optional parameters. | |
| size | Long | No | The default file size, in bytes. If this field is not empty, the organization storage system verifies whether the actual file size matches this value. A mismatch causes an error. | |
| conflictStrategy | String | No | The file name conflict strategy. - AUTO_RENAME: Automatically rename. Default. - OVERWRITE: Overwrite. - RETURN_DENTRY_IF_EXISTS: Return the existing file. - RETURN_ERROR_IF_EXISTS: Return an error if the file already exists. | |
| appProperties | Array | No | The app property list of the current file. Maximum: 3. | |
| name | String | Yes | The property name. The property name must be unique within the current app. Properties with the same name across different apps do not affect each other. | |
| value | String | Yes | The property value. | |
| visibility | String | Yes | The property visibility. - PUBLIC: Visible to all apps. - PRIVATE: Visible only to the current app. | |
| convertToOnlineDoc | Boolean | No | Whether to convert to an online document. - false (default): No. - true: Yes. |
Request example
HTTPresponse
response body
| Name | Type | Description |
|---|---|---|
| dentry | Object | File information. |
| id | String | The file ID. |
| spaceId | String | The ID of the space the file belongs to. |
| parentId | String | The parent directory ID. For the root directory, this value is 0. An empty value means the root directory has no parentId. |
| type | String | The type, either directory or file. Enum values: - FILE: File. - FOLDER: Folder. |
| name | String | The file name. |
| size | Long | The file size, in bytes. |
| path | String | The file path within the space. |
| version | Long | The version. |
| status | String | The status: - NORMAL: Normal. - DELETED: Deleted. - EXPIRED: Expired. |
| extension | String | The file extension. |
| creatorId | String | The unionId of the creator. |
| modifierId | String | The unionId of the modifier. |
| createTime | String | The created time in ISO 8601 format, for example, 2022-07-29T14:55Z. |
| modifiedTime | String | The modified time in ISO 8601 format, for example, 2022-07-29T14:55Z. |
| properties | Object | File properties. |
| readOnly | Boolean | Whether the file is read-only. - true: Yes. - false: No. |
| appProperties | Map<String, Array> | Properties on specific apps. The key is the ownerId of the space, and the value is the property list. |
| Array | The property list. | |
| name | String | The property name. |
| value | String | The property value. |
| visibility | String | The property visibility. - PUBLIC: Visible to all apps. - PRIVATE: Visible only to the current app. |
| uuid | String | The unique identifier uuid. This field does not change when the file is moved. |
| partitionType | String | The storage partition: - PUBLIC_OSS_PARTITION: Public cloud OSS storage partition. - MINI_OSS_PARTITION: Dedicated MiniOSS storage partition. |
| storageDriver | String | The driver type. Enum values: - DINGTALK: DingTalk unified storage driver. - ALIDOC: DingTalk Docs storage driver. - SHANJI: Shanji storage driver. - UNKNOWN: Unknown driver. |
| thumbnail | Object | Thumbnail information. |
| width | Integer | The thumbnail width. |
| height | Integer | The thumbnail height. |
| url | String | The thumbnail URL. |
| category | String | The category. Enum values: - IMAGE: Image. - VIDEO: Video. - AUDIO: Audio. - ARCHIVE: Archive. - SHORTCUT: Shortcut. - DOCUMENT: Document. - ALI_DOC: DingTalk Docs. - OTHER: Other. |
Response body example
Error codes
If an error is returned when you call this API, find a solution by error message in the Global error codes document.| HttpCode | Error code | Error message | Description |
|---|---|---|---|
| 400 | operationConcurrentControl | %s | Concurrency control. |
| 400 | paramError | %s | Parameter error. |
| 400 | paramError.parentDentryUuid | %s | Parameter error - parentDentryUuid. |
| 400 | paramError.uploadKey | %s | Parameter error - uploadKey. |
| 400 | paramError.name | %s | Parameter error - name. |
| 400 | paramError.conflictStrategy | %s | Parameter error - conflictStrategy. |
| 400 | spaceQuotaInsufficient | %s | Insufficient space quota. |
| 400 | sceneQuotaInsufficient | %s | Insufficient scene quota. |
| 400 | appQuotaInsufficient | %s | Insufficient app quota. |
| 400 | orgQuotaInsufficient | %s | Insufficient organization quota. |
| 400 | dentryNameIllegal | %s | Illegal file name. |
| 400 | dentryStoreError | %s | File storage error. |
| 400 | dentryNameConflict | %s | File name conflict. |
| 400 | dentryFormatNotSupport | %s | Unsupported file format. |
| 403 | permissionDenied | %s | The user lacks permission to upload the file. |
| 404 | spaceNotExist | %s | The space does not exist. |
| 500 | systemError | %s | System error. |
| 500 | unknownError | Unknown Error | Unknown error. |
| 503 | operationTimeout | %s | Request timeout. |