Add a space - DingTalk Help Center

Call this API to create a new space in your organization’s cloud drive. Within the space, you can create folders, upload files, and perform other actions.

API call description

About storage spaces

A storage space is part of your organization’s cloud drive, but spaces created through this API are not visible on the client-side cloud drive.
A storage space consumes the capacity of your organization’s cloud drive.

Storage space types

User space (USER): Files in this space can only be granted permanent permissions, and the grantor must hold management permissions to grant access.
App space (APP): Files in this space can only be granted temporary permissions, and the grantor is not required to hold management permissions.

Request

Basic information

Field	Value
HTTP URL	https://api.dingtalk.io/v1.0/storage/spaces
HTTP Method	POST
Supported app types	appType-Internal app　appType-Third-party enterprise app
Required permissions	permission-Storage.Space.Write-Organization storage space 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 internal apps, call the Obtain the access token of an internal app API. - For third-party enterprise apps, call the Obtain the access token of the authorized enterprise API.

Query parameter

Name	Type	Required	Description
unionId	String	Yes	The unionId of the operator. Obtain it by calling the Query user details API.

Request body

Name	Type	Required	Description
option	Object	No	Optional parameters.
name	String	No	The space name. No name is set by default.
quota	Long	No	The maximum capacity of the space, in bytes. If this parameter is not specified, the space has no specific capacity limit, but it cannot exceed the total capacity of your organization’s cloud drive.
capabilities	Object	No	The capability options of the space. By default, no extended capabilities are set.
canSearch	Boolean	No	Whether search is supported. - true: Supported. - false: Not supported. This is the default value.
canRename	Boolean	No	Whether renaming the space is supported. - true: Supported. - false: Not supported. This is the default value.
canRecordRecentFile	Boolean	No	Whether the space can be included in the Recently Used list. - true: Supported. - false: Not supported. This is the default value.
scene	String	No	The space scene. This value is defined by the developer. - If this parameter is not specified, the default value is default. - If the combination of this parameter and sceneId already exists, this API returns the previously created space and does not create a new one.
sceneId	String	No	The space scene ID. This value is defined by the developer. - If this parameter is not specified, the default value is 0. - If the combination of sceneId and this parameter already exists, this API returns the previously created space and does not create a new one.
ownerType	String	No	The owner type. - USER: User type. This is the default value. - APP: App type.

Request example

HTTP

POST /v1.0/storage/spaces?unionId=cHtUYxxxxx HTTP/1.1
Host:api.dingtalk.io
x-acs-dingtalk-access-token:xxxxx
Content-Type:application/json

{
  "option" : {
    "name" : "Test space",
    "quota" : 1024,
    "capabilities" : {
      "canSearch" : true,
      "canRename" : true,
      "canRecordRecentFile" : true
    },
    "scene" : "scene",
    "sceneId" : "123",
    "ownerType" : "USER"
  }
}

Java

// This file is auto-generated, don't edit it. Thanks.
package com.aliyun.sample;

import com.aliyun.tea.*;
import com.aliyun.teautil.*;
import com.aliyun.teautil.models.*;
import com.aliyun.dingtalkstorage_1_0.*;
import com.aliyun.dingtalkstorage_1_0.models.*;
import com.aliyun.teaopenapi.*;
import com.aliyun.teaopenapi.models.*;

public class Sample {

    /**
     * Initialize the account client with a token
     * @return Client
     * @throws Exception
     */
    public static com.aliyun.dingtalkstorage_1_0.Client createClient() throws Exception {
        Config config = new Config();
        config.protocol = "https";
        config.regionId = "central";
        return new com.aliyun.dingtalkstorage_1_0.Client(config);
    }

    public static void main(String[] args_) throws Exception {
        java.util.List<String> args = java.util.Arrays.asList(args_);
        com.aliyun.dingtalkstorage_1_0.Client client = Sample.createClient();
        AddSpaceHeaders addSpaceHeaders = new AddSpaceHeaders();
        addSpaceHeaders.xAcsDingtalkAccessToken = "<your access token>";
        AddSpaceRequest.AddSpaceRequestOptionCapabilities optionCapabilities = new AddSpaceRequest.AddSpaceRequestOptionCapabilities()
                .setCanSearch(true)
                .setCanRename(true)
                .setCanRecordRecentFile(true);
        AddSpaceRequest.AddSpaceRequestOption option = new AddSpaceRequest.AddSpaceRequestOption()
                .setName("Test space")
                .setQuota(1024L)
                .setCapabilities(optionCapabilities)
                .setScene("scene")
                .setSceneId("123")
                .setOwnerType("USER");
        AddSpaceRequest addSpaceRequest = new AddSpaceRequest()
                .setUnionId("cHtUYxxxxx")
                .setOption(option);
        try {
            client.addSpaceWithOptions(addSpaceRequest, addSpaceHeaders, new RuntimeOptions());
        } catch (TeaException err) {
            if (!com.aliyun.teautil.Common.empty(err.code) && !com.aliyun.teautil.Common.empty(err.message)) {
                // err contains the code and message attributes that help you locate the issue
            }

        } catch (Exception _err) {
            TeaException err = new TeaException(_err.getMessage(), _err);
            if (!com.aliyun.teautil.Common.empty(err.code) && !com.aliyun.teautil.Common.empty(err.message)) {
                // err contains the code and message attributes that help you locate the issue
            }

        }        
    }
}

Python

# -*- coding: utf-8 -*-
# This file is auto-generated, don't edit it. Thanks.
import sys

from typing import List

from alibabacloud_dingtalk.storage_1_0.client import Client as dingtalkstorage_1_0Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_dingtalk.storage_1_0 import models as dingtalkstorage__1__0_models
from alibabacloud_tea_util import models as util_models
from alibabacloud_tea_util.client import Client as UtilClient

class Sample:
    def __init__(self):
        pass

    @staticmethod
    def create_client() -> dingtalkstorage_1_0Client:
        """
        Initialize the account client with a token
        @return: Client
        @throws Exception
        """
        config = open_api_models.Config()
        config.protocol = 'https'
        config.region_id = 'central'
        return dingtalkstorage_1_0Client(config)

    @staticmethod
    def main(
        args: List[str],
    ) -> None:
        client = Sample.create_client()
        add_space_headers = dingtalkstorage__1__0_models.AddSpaceHeaders()
        add_space_headers.x_acs_dingtalk_access_token = '<your access token>'
        option_capabilities = dingtalkstorage__1__0_models.AddSpaceRequestOptionCapabilities(
            can_search=True,
            can_rename=True,
            can_record_recent_file=True
        )
        option = dingtalkstorage__1__0_models.AddSpaceRequestOption(
            name='Test space',
            quota=1024,
            capabilities=option_capabilities,
            scene='scene',
            scene_id='123',
            owner_type='USER'
        )
        add_space_request = dingtalkstorage__1__0_models.AddSpaceRequest(
            union_id='cHtUYxxxxx',
            option=option
        )
        try:
            client.add_space_with_options(add_space_request, add_space_headers, util_models.RuntimeOptions())
        except Exception as err:
            if not UtilClient.empty(err.code) and not UtilClient.empty(err.message):
                # err contains the code and message attributes that help you locate the issue
                pass

    @staticmethod
    async def main_async(
        args: List[str],
    ) -> None:
        client = Sample.create_client()
        add_space_headers = dingtalkstorage__1__0_models.AddSpaceHeaders()
        add_space_headers.x_acs_dingtalk_access_token = '<your access token>'
        option_capabilities = dingtalkstorage__1__0_models.AddSpaceRequestOptionCapabilities(
            can_search=True,
            can_rename=True,
            can_record_recent_file=True
        )
        option = dingtalkstorage__1__0_models.AddSpaceRequestOption(
            name='Test space',
            quota=1024,
            capabilities=option_capabilities,
            scene='scene',
            scene_id='123',
            owner_type='USER'
        )
        add_space_request = dingtalkstorage__1__0_models.AddSpaceRequest(
            union_id='cHtUYxxxxx',
            option=option
        )
        try:
            await client.add_space_with_options_async(add_space_request, add_space_headers, util_models.RuntimeOptions())
        except Exception as err:
            if not UtilClient.empty(err.code) and not UtilClient.empty(err.message):
                # err contains the code and message attributes that help you locate the issue
                pass

if __name__ == '__main__':
    Sample.main(sys.argv[1:])

PHP

<?php

// This file is auto-generated, don't edit it. Thanks.
namespace AlibabaCloud\SDK\Sample;

use AlibabaCloud\SDK\Dingtalk\Vstorage_1_0\Dingtalk;
use \Exception;
use AlibabaCloud\Tea\Exception\TeaError;
use AlibabaCloud\Tea\Utils\Utils;

use Darabonba\OpenApi\Models\Config;
use AlibabaCloud\SDK\Dingtalk\Vstorage_1_0\Models\AddSpaceHeaders;
use AlibabaCloud\SDK\Dingtalk\Vstorage_1_0\Models\AddSpaceRequest\option\capabilities;
use AlibabaCloud\SDK\Dingtalk\Vstorage_1_0\Models\AddSpaceRequest\option;
use AlibabaCloud\SDK\Dingtalk\Vstorage_1_0\Models\AddSpaceRequest;
use AlibabaCloud\Tea\Utils\Utils\RuntimeOptions;

class Sample {

    /**
     * Initialize the account client with a token
     * @return Dingtalk Client
     */
    public static function createClient(){
        $config = new Config([]);
        $config->protocol = "https";
        $config->regionId = "central";
        return new Dingtalk($config);
    }

    /**
     * @param string[] $args
     * @return void
     */
    public static function main($args){
        $client = self::createClient();
        $addSpaceHeaders = new AddSpaceHeaders([]);
        $addSpaceHeaders->xAcsDingtalkAccessToken = "<your access token>";
        $optionCapabilities = new capabilities([
            "canSearch" => true,
            "canRename" => true,
            "canRecordRecentFile" => true
        ]);
        $option = new option([
            "name" => "Test space",
            "quota" => 1024,
            "capabilities" => $optionCapabilities,
            "scene" => "scene",
            "sceneId" => "123",
            "ownerType" => "USER"
        ]);
        $addSpaceRequest = new AddSpaceRequest([
            "unionId" => "cHtUYxxxxx",
            "option" => $option
        ]);
        try {
            $client->addSpaceWithOptions($addSpaceRequest, $addSpaceHeaders, new RuntimeOptions([]));
        }
        catch (Exception $err) {
            if (!($err instanceof TeaError)) {
                $err = new TeaError([], $err->getMessage(), $err->getCode(), $err);
            }
            if (!Utils::empty_($err->code) && !Utils::empty_($err->message)) {
                // err contains the code and message attributes that help you locate the issue
            }
        }
    }
}
$path = __DIR__ . \DIRECTORY_SEPARATOR . '..' . \DIRECTORY_SEPARATOR . 'vendor' . \DIRECTORY_SEPARATOR . 'autoload.php';
if (file_exists($path)) {
    require_once $path;
}
Sample::main(array_slice($argv, 1));

// This file is auto-generated, don't edit it. Thanks.
package main

import (
  "os"
  util  "github.com/alibabacloud-go/tea-utils/service"
  dingtalkstorage_1_0  "github.com/alibabacloud-go/dingtalk/storage_1_0"
  openapi  "github.com/alibabacloud-go/darabonba-openapi/client"
  "github.com/alibabacloud-go/tea/tea"
)

/**
 * Initialize the account client with a token
 * @return Client
 * @throws Exception
 */
func CreateClient () (_result *dingtalkstorage_1_0.Client, _err error) {
  config := &openapi.Config{}
  config.Protocol = tea.String("https")
  config.RegionId = tea.String("central")
  _result = &dingtalkstorage_1_0.Client{}
  _result, _err = dingtalkstorage_1_0.NewClient(config)
  return _result, _err
}

func _main (args []*string) (_err error) {
  client, _err := CreateClient()
  if _err != nil {
    return _err
  }

  addSpaceHeaders := &dingtalkstorage_1_0.AddSpaceHeaders{}
  addSpaceHeaders.XAcsDingtalkAccessToken = tea.String("<your access token>")
  optionCapabilities := &dingtalkstorage_1_0.AddSpaceRequestOptionCapabilities{
    CanSearch: tea.Bool(true),
    CanRename: tea.Bool(true),
    CanRecordRecentFile: tea.Bool(true),
  }
  option := &dingtalkstorage_1_0.AddSpaceRequestOption{
    Name: tea.String("Test space"),
    Quota: tea.Int64(1024),
    Capabilities: optionCapabilities,
    Scene: tea.String("scene"),
    SceneId: tea.String("123"),
    OwnerType: tea.String("USER"),
  }
  addSpaceRequest := &dingtalkstorage_1_0.AddSpaceRequest{
    UnionId: tea.String("cHtUYxxxxx"),
    Option: option,
  }
  tryErr := func()(_e error) {
    defer func() {
      if r := tea.Recover(recover()); r != nil {
        _e = r
      }
    }()
    _, _err = client.AddSpaceWithOptions(addSpaceRequest, addSpaceHeaders, &util.RuntimeOptions{})
    if _err != nil {
      return _err
    }

    return nil
  }()

  if tryErr != nil {
    var err = &tea.SDKError{}
    if _t, ok := tryErr.(*tea.SDKError); ok {
      err = _t
    } else {
      err.Message = tea.String(tryErr.Error())
    }
    if !tea.BoolValue(util.Empty(err.Code)) && !tea.BoolValue(util.Empty(err.Message)) {
      // err contains the code and message attributes that help you locate the issue
    }

  }
  return _err
}

func main() {
  err := _main(tea.StringSlice(os.Args[1:]))
  if err != nil {
    panic(err)
  }
}

Node.js

// This file is auto-generated, don't edit it
import Util, * as $Util from '@alicloud/tea-util';
import dingtalkstorage_1_0, * as $dingtalkstorage_1_0 from '@alicloud/dingtalk/storage_1_0';
import OpenApi, * as $OpenApi from '@alicloud/openapi-client';
import * as $tea from '@alicloud/tea-typescript';

export default class Client {

  /**
   * Initialize the account client with a token
   * @return Client
   * @throws Exception
   */
  static createClient(): dingtalkstorage_1_0 {
    let config = new $OpenApi.Config({ });
    config.protocol = "https";
    config.regionId = "central";
    return new dingtalkstorage_1_0(config);
  }

  static async main(args: string[]): Promise<void> {
    let client = Client.createClient();
    let addSpaceHeaders = new $dingtalkstorage_1_0.AddSpaceHeaders({ });
    addSpaceHeaders.xAcsDingtalkAccessToken = "<your access token>";
    let optionCapabilities = new $dingtalkstorage_1_0.AddSpaceRequestOptionCapabilities({
      canSearch: true,
      canRename: true,
      canRecordRecentFile: true,
    });
    let option = new $dingtalkstorage_1_0.AddSpaceRequestOption({
      name: "Test space",
      quota: 1024,
      capabilities: optionCapabilities,
      scene: "scene",
      sceneId: "123",
      ownerType: "USER",
    });
    let addSpaceRequest = new $dingtalkstorage_1_0.AddSpaceRequest({
      unionId: "cHtUYxxxxx",
      option: option,
    });
    try {
      await client.addSpaceWithOptions(addSpaceRequest, addSpaceHeaders, new $Util.RuntimeOptions({ }));
    } catch (err) {
      if (!Util.empty(err.code) && !Util.empty(err.message)) {
        // err contains the code and message attributes that help you locate the issue
      }

    }    
  }

}

Client.main(process.argv.slice(2));

// This file is auto-generated, don't edit it. Thanks.

using System;
using System.Collections;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;

using Tea;
using Tea.Utils;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample 
    {

        /**
         * Initialize the account client with a token
         * @return Client
         * @throws Exception
         */
        public static AlibabaCloud.SDK.Dingtalkstorage_1_0.Client CreateClient()
        {
            AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config();
            config.Protocol = "https";
            config.RegionId = "central";
            return new AlibabaCloud.SDK.Dingtalkstorage_1_0.Client(config);
        }

        public static void Main(string[] args)
        {
            AlibabaCloud.SDK.Dingtalkstorage_1_0.Client client = CreateClient();
            AlibabaCloud.SDK.Dingtalkstorage_1_0.Models.AddSpaceHeaders addSpaceHeaders = new AlibabaCloud.SDK.Dingtalkstorage_1_0.Models.AddSpaceHeaders();
            addSpaceHeaders.XAcsDingtalkAccessToken = "<your access token>";
            AlibabaCloud.SDK.Dingtalkstorage_1_0.Models.AddSpaceRequest.AddSpaceRequestOption.AddSpaceRequestOptionCapabilities optionCapabilities = new AlibabaCloud.SDK.Dingtalkstorage_1_0.Models.AddSpaceRequest.AddSpaceRequestOption.AddSpaceRequestOptionCapabilities
            {
                CanSearch = true,
                CanRename = true,
                CanRecordRecentFile = true,
            };
            AlibabaCloud.SDK.Dingtalkstorage_1_0.Models.AddSpaceRequest.AddSpaceRequestOption option = new AlibabaCloud.SDK.Dingtalkstorage_1_0.Models.AddSpaceRequest.AddSpaceRequestOption
            {
                Name = "Test space",
                Quota = 1024,
                Capabilities = optionCapabilities,
                Scene = "scene",
                SceneId = "123",
                OwnerType = "USER",
            };
            AlibabaCloud.SDK.Dingtalkstorage_1_0.Models.AddSpaceRequest addSpaceRequest = new AlibabaCloud.SDK.Dingtalkstorage_1_0.Models.AddSpaceRequest
            {
                UnionId = "cHtUYxxxxx",
                Option = option,
            };
            try
            {
                client.AddSpaceWithOptions(addSpaceRequest, addSpaceHeaders, new AlibabaCloud.TeaUtil.Models.RuntimeOptions());
            }
            catch (TeaException err)
            {
                if (!AlibabaCloud.TeaUtil.Common.Empty(err.Code) && !AlibabaCloud.TeaUtil.Common.Empty(err.Message))
                {
                    // err contains the code and message attributes that help you locate the issue
                }
            }
            catch (Exception _err)
            {
                TeaException err = new TeaException(new Dictionary<string, object>
                {
                    { "message", _err.Message }
                });
                if (!AlibabaCloud.TeaUtil.Common.Empty(err.Code) && !AlibabaCloud.TeaUtil.Common.Empty(err.Message))
                {
                    // err contains the code and message attributes that help you locate the issue
                }
            }
        }

    }
}

Response

Response body

Name	Type	Description
space	Object	The space information.
id	String	The space ID.
corpId	String	The organization ID where the space resides.
creatorId	String	The unionId of the creator.
ownerType	String	The owner type. - USER: User type. This is the default value. - APP: App type.
ownerId	String	The owner identifier.
modifierId	String	The unionId of the last modifier.
usedQuota	Long	The used capacity, in bytes.
quota	Long	The total capacity, in bytes.
status	String	The space status. - NORMAL: Normal. - DELETE: Trash.
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.
appId	String	The appId on the Open Platform.
scene	String	The business scene.
sceneId	String	The space scene ID.
capabilities	Object	The capability options of the space.
canSearch	Boolean	Whether search is supported. - true: Supported. - false: Not supported. This is the default value.
canRename	Boolean	Whether renaming the space is supported. - true: Supported. - false: Not supported. This is the default value.
canRecordRecentFile	Boolean	Whether the space can be included in the Recently Used list. - true: Supported. - false: Not supported. This is the default value.
name	String	The space name.
partitions	Array	The partition capacity information. The maximum value is 2.
partitionType	String	The partition type. - PUBLIC_OSS_PARTITION: Public cloud OSS storage partition. - MINI_OSS_PARTITION: Dedicated Mini OSS storage partition.
quota	Object	The capacity information.
used	Long	The actual used capacity, in bytes. The minimum value is 0. This represents the total capacity occupied by all files under the app. File upload, copy, and delete operations update the value of used accordingly.
max	Long	The maximum capacity, in bytes. - When the current app capacity is set to max, the app has an upper capacity limit, and the value of used cannot exceed the value of max. - When the current app capacity is not set to max, this field returns empty, and the app shares the remaining available capacity of the organization.
reserved	Long	The remaining pre-allocated capacity, in bytes. The admin console can pre-allocate capacity to an app or space. This field indicates the remaining pre-allocated capacity, that is, the unused portion of the pre-allocated capacity. If no pre-allocated capacity is set, this field is empty.
type	String	The capacity type. - SHARE: Shared capacity. In this mode, Quota.max is empty, indicating that the app shares the organization’s capacity. - PRIVATE: Pre-allocated capacity (dedicated capacity). In this mode, after Quota.max is set, the capacity is exclusive. Use pre-allocated (dedicated) capacity when you need to ensure that the available capacity of a single app is not affected by other apps.

Response body example

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

{
  "space" : {
    "id" : "833xxxxx",
    "corpId" : "ding027xxxxx",
    "creatorId" : "cHtUYxxxxx",
    "ownerType" : "USER",
    "ownerId" : "xxxxx",
    "modifierId" : "cHtUYxxxxx",
    "usedQuota" : 1024,
    "quota" : 1048576,
    "status" : "NORMAL",
    "createTime" : "2022-01-01T10:00:00Z",
    "modifiedTime" : "2022-01-01T10:00:00Z",
    "scene" : "scene",
    "sceneId" : "123",
    "capabilities" : {
      "canSearch" : true,
      "canRename" : true,
      "canRecordRecentFile" : true
    },
    "name" : "Test space"
  }
}

Error codes

If an error occurs when you call this API, look up the solution in the Global error codes documentation based on the error message.

HttpCode	Error code	Error message	Description
400	paramError	%s	Parameter error.
400	paramError.name	%s	Parameter error - name.
400	paramError.scene	%s	Parameter error - scene.
400	paramError.sceneId	%s	Parameter error - sceneId.
403	permissionDenied	%s	The user lacks permission to create a space.
500	systemError	%s	System error.
500	unknownError	Unknown Error	Unknown error.
503	operationTimeout	%s	Request timed out.

​API call description

​About storage spaces

​Storage space types

​Request

​Basic information

​Request header

​Query parameter

​Request body

​Request example

​Response

​Response body

​Response body example

​Error codes