API call description
Description
- If the
spaceIdparameter is provided when uploading a file, use the Get file upload information API. - If the
dentryUuidoruuidparameter is provided when uploading a file, this document is recommended.
resourceUrls and headers parameter values required for file upload.
Step 2: Upload the file using the OSS header signature method. Refer to the following examples:
Java
Description
- When the storage space type is USER, users with permission to the space have action permissions. Other employees must call the Add permissions API for authorization.
- When the storage space type is APP, anyone performing actions must call the Add permissions API for authorization.
Request
Basic information
| Field | Value |
|---|---|
| HTTP URL | https://api.dingtalk.io/v2.0/storage/spaces/files/{parentDentryUuid}/uploadInfos/query |
| HTTP Method | POST |
| Supported app types | appType-Internal app appType-Third-party enterprise app |
| Permissions required | permission-Storage.UploadInfo.Read-Read permission for organization storage file upload information |
Request header
| Name | Type | Required | Description |
|---|---|---|---|
| x-acs-dingtalk-access-token | String | Yes | The access credential for calling this API. Obtain it in the following ways: - For an internal app, call the Get the access token of an internal app API. - For a third-party enterprise app, call the Get the access token of an authorized organization for a third-party app API. |
Path parameter
| Name | Type | Required | Description |
|---|---|---|---|
| parentDentryUuid | String | Yes | The dentryUuid of the parent node. Call the Search for files or Get dentryUuid information API to obtain the value of the returned dentryUuid field. 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 operator. Call the Query user details API to obtain it. |
Request body
| Name | Type | Required | Description | |
|---|---|---|---|---|
| protocol | String | Yes | Returns information required for different upload protocols based on the specified protocol. - HEADER_SIGNATURE: Header signature | |
| option | Object | No | Optional parameters. | |
| storageDriver | String | No | The file storage driver type. Currently, only DINGTALK is supported. | |
| preCheckParam | Object | No | Fields for pre-check. Used to validate the file name, file integrity, and capacity. | |
| size | Long | No | The file size, used for capacity-related validation. If not provided, no validation is performed. | |
| name | String | No | The file name (used for file name validity and file name conflict checks). Rules: - Leading and trailing spaces are not allowed and will be automatically removed. - Cannot contain special characters, including: tab, *, ", <, >, ` | . - Cannot end with .`. |
| preferRegion | String | No | The preferred region: - ZHANGJIAKOU: Zhangjiakou - SHENZHEN: Shenzhen - SHANGHAI: Shanghai - SINGAPORE: Singapore - UNKNOWN: Unknown Specifies the region where the resource is preferably stored, enabling features such as nearby upload. | |
| preferIntranet | Boolean | No | Whether to prioritize intranet transmission. This parameter requires dedicated storage intranet transmission to be configured. - true: Yes (default) - false: No |
Request example
HTTPResponse
Response body
| Name | Type | Description |
|---|---|---|
| uploadKey | String | The unique identifier for the upload. |
| storageDriver | String | The file storage type. |
| protocol | String | The upload protocol: - HEADER_SIGNATURE: Header signature |
| headerSignatureInfo | Object | The header signature upload information. Returned when the protocol parameter is set to HEADER_SIGNATURE. |
| resourceUrls | Array of String | The transmission URLs. |
| headers | Map<String, String> | The request headers. Maximum size: 20. |
| expirationSeconds | Integer | The expiration time, in seconds. |
| region | String | The region. Enum values: - ZHANGJIAKOU: Zhangjiakou - SHENZHEN: Shenzhen - SHANGHAI: Shanghai - SINGAPORE: Singapore - UNKNOWN: Unknown |
| internalResourceUrls | Array of String | The intranet URLs. This field is currently unused. Please ignore it. |
Response body example
Error codes
If an error occurs when calling this API, look up the error message in the Global error codes document for a solution.| HttpCode | Error code | Error message | Description |
|---|---|---|---|
| 400 | paramError | %s | Parameter error |
| 400 | paramError.protocol | %s | Parameter error - protocol |
| 400 | paramError.parentDentryUuid | %s | Parameter error - parentDentryUuid |
| 400 | paramError.storageDriver | %s | Parameter error - storageDriver |
| 400 | dentryUploadError | %s | File upload error |
| 400 | spaceQuotaInsufficient | %s | Insufficient space capacity |
| 400 | sceneQuotaInsufficient | %s | Insufficient scene capacity |
| 400 | appQuotaInsufficient | %s | Insufficient app capacity |
| 400 | orgQuotaInsufficient | %s | Insufficient organization capacity |
| 400 | dentryUploadForbidden | %s | Upload forbidden |
| 400 | dentryUploadProtocolNotSupport | %s | Unsupported upload protocol |
| 403 | permissionDenied | %s | User lacks permission to upload files |
| 404 | spaceNotExist | %s | Space does not exist |
| 500 | systemError | %s | System error |
| 500 | unknownError | Unknown Error | Unknown error |
| 503 | operationTimeout | %s | Request timeout |