Overview

CloudBase Flutter SDK enables you to use CloudBase capabilities in Flutter applications, including authentication, data models, MySQL database, cloud functions, cloud hosting, APIs, and more. For usage, please refer to CloudBase Flutter SDK, or check the sample code.

Note

CloudBase Flutter SDK is fully aligned with HTTP API

SDK is categorized by functionality:

Authentication: API methods for user registration and login, supporting multiple login methods.
Session Management: API methods for managing user session state and tokens.
User Management: API methods for retrieving, updating, and managing user information.
Identity Source Management: API methods for managing third-party identity source binding and unbinding.
Password Management: API methods for password reset and change.
Verification Management: API methods for verification code sending, verification, resending, CAPTCHA creation, verification, and management.
Data Model: Data model CRUD operations.
Data Source Query: Query data source aggregation list, details, Schema, and table names.
MySQL Database: MySQL RESTful database operations.
Cloud Functions: Call cloud functions and function-type cloud hosting.
Cloud Hosting: Call cloud hosting container services.
APIs: Call APIs interfaces.
Cloud Storage: File upload, download, delete, copy, move, and other operations.

Basic Usage Example

accessKey can be generated in CloudBase Platform/API Key Configuration

import 'package:cloudbase_flutter/cloudbase_flutter.dart';

// Initialize (async)
final app = await CloudBase.init(
  env: 'your-env-id',       // Replace with your environment ID
  region: 'ap-shanghai',     // Region, default is Shanghai
  accessKey: 'your-key',     // Fill in the generated Publishable Key
  authConfig: AuthConfig(
    detectSessionInUrl: true, // Optional: automatically detect OAuth parameters in URL
  ),
);

final auth = app.auth;

// Check login status
Future<bool> checkAuthStatus() async {
  final result = await auth.getSession();

  if (result.error != null) {
    print('Failed to check login status: ${result.error!.message}');
    return false;
  }

  if (result.data?.session != null) {
    print('User is logged in: ${result.data!.user?.id}');
    return true;
  } else {
    print('User is not logged in');
    return false;
  }
}

// User registration example (two-step verification flow)
Future<void> registerUser(String email, String password) async {
  // Step 1: Send verification code
  final signUpResult = await auth.signUp(SignUpReq(
    email: email,
    password: password,
  ));

  if (signUpResult.error != null) {
    print('Failed to send verification code: ${signUpResult.error!.message}');
    return;
  }

  print('Verification code sent, waiting for user input...');

  // Step 2: Verify verification code and complete registration
  final verifyResult = await signUpResult.data!.verifyOtp!(
    VerifyOtpParams(token: 'User input verification code'),
  );

  if (verifyResult.error != null) {
    print('Registration failed: ${verifyResult.error!.message}');
  } else {
    print('Registration successful: ${verifyResult.data?.user?.id}');
  }
}

// Password login example
Future<void> loginWithPassword(String email, String password) async {
  final result = await auth.signInWithPassword(
    SignInWithPasswordReq(email: email, password: password),
  );

  if (result.error != null) {
    print('Login failed: ${result.error!.message}');
  } else {
    print('Login successful: ${result.data?.user?.id}');
    print('Access Token: ${result.data?.session?.accessToken}');
  }
}

// Logout example
Future<void> logout() async {
  await auth.signOut();
  print('Logged out');
}

// Listen for authentication state changes
final result = auth.onAuthStateChange((event, session, info) {
  switch (event) {
    case AuthStateChangeEvent.signedIn:
      print('User signed in');
      break;
    case AuthStateChangeEvent.signedOut:
      print('User signed out');
      break;
    case AuthStateChangeEvent.tokenRefreshed:
      print('Token refreshed');
      break;
    case AuthStateChangeEvent.userUpdated:
      print('User info updated');
      break;
    default:
      break;
  }
});

// Unsubscribe
result.data?.subscription.unsubscribe();

// Call cloud function example
final result = await app.callFunction(
  name: 'myFunction',
  data: {'key': 'value'},
);

if (result.isSuccess) {
  print('Execution result: ${result.result}');
} else {
  print('Execution failed: ${result.message}');
}

Authentication

Future<SignUpRes> auth.signUp(SignUpReq params)

Creates a new user account
Uses smart registration and login flow: send verification code → wait for user input → smart judgment of user existence → auto login or register and login
If user already exists, directly login; if user does not exist, register new user and auto login

参数

params

SignUpReq

Future

SignUpRes

dataSignUpResData

verifyOtp

可选

Future<SignInRes> Function(VerifyOtpParams)?

Verification code callback function, used to verify user input verification code

errorAuthError?

Error info, null when successful

示例

signInAnonymously

Future<SignInRes> auth.signInAnonymously({String? providerToken})

Anonymous login, creates a temporary anonymous user account.

Creates a temporary anonymous user account
No identity verification info needed
Suitable for scenarios requiring temporary access

参数

providerToken

String?

Third-party platform token, used to associate third-party platform identity

Future

SignInRes

示例

signInWithPassword

Future<SignInRes> auth.signInWithPassword(SignInWithPasswordReq params)

参数

params

SignInWithPasswordReq

Future

SignInRes

示例

signInWithOtp

Future<SignInWithOtpRes> auth.signInWithOtp(SignInWithOtpReq params)

Login with OTP (one-time verification code). After calling, a verification code will be sent. You need to complete verification through the returned verifyOtp callback.

If the user does not exist, a user will be created by default. You can control whether to automatically create a user with the shouldCreateUser parameter (default is true)

参数

params

SignInWithOtpReq

Future

SignInWithOtpRes

dataSignInWithOtpResData

verifyOtp

可选

Future<SignInRes> Function(VerifyOtpParams)?

Verification code callback function

errorAuthError?

Error info, null when successful

示例

signInWithOAuth

Future<SignInOAuthRes> auth.signInWithOAuth(SignInWithOAuthReq params)

Login with OAuth third-party platform. Returns authorization URL, you need to guide the user to redirect to this URL to complete authorization.

参数

params

SignInWithOAuthReq

Future

SignInOAuthRes

示例

signInWithIdToken

Future<SignInRes> auth.signInWithIdToken(SignInWithIdTokenReq params)

参数

params

SignInWithIdTokenReq

Future

SignInRes

示例

signInWithCustomTicket

Future<SignInRes> auth.signInWithCustomTicket(Future<String> Function() getTicketFn)

Login with custom ticket. By passing an async function to get the ticket, the server generates the ticket and completes the login.

参数

getTicketFn

Future<String> Function()

Async function to get custom login ticket

Future

SignInRes

示例

Session Management

getSession

Future<SignInRes> auth.getSession();

Get current session. If token has expired, it will be automatically refreshed.

参数

无参数

Future

SignInRes

示例

refreshSession

Future<SignInRes> auth.refreshSession([String? refreshToken])

Refresh session. Use Refresh Token to get a new Access Token.

参数

refreshToken

String?

Refresh token (optional, defaults to current session's refreshToken)

Future

SignInRes

示例

setSession

Future<SignInRes> auth.setSession(SetSessionReq params)

Set session. Restore session state with Refresh Token.

参数

params

SetSessionReq

Future

SignInRes

示例

signOut

Future<SignOutRes> auth.signOut([SignOutReq? params])

Logout. Clear local session and notify server to revoke token.

参数

params

SignOutReq?

Logout configuration options (optional)

Future

SignOutRes

示例

onAuthStateChange

OnAuthStateChangeResult auth.onAuthStateChange(OnAuthStateChangeCallback callback)

Listen for authentication state changes. Supports listening for login, logout, token refresh, and user update events.

参数

callback

void Function(AuthStateChangeEvent, Session?, AuthStateChangeInfo?)

State change callback function

OnAuthStateChangeResult

示例

getClaims

Future<GetClaimsRes> auth.getClaims();

Get JWT Claims of current Access Token (token claims).

参数

无参数

Future

GetClaimsRes

示例

User Management

getUser

Future<GetUserRes> auth.getUser();

Get current logged-in user info.

参数

无参数

Future

GetUserRes

示例

refreshUser

Future<SignInRes> auth.refreshUser();

Refresh user info. Re-fetch the latest user data from server and update local session.

参数

无参数

Future

SignInRes

示例

updateUser

Future<UpdateUserRes> auth.updateUser(UpdateUserReq params)

Update user info. If updating email or phone number, verification code verification is required.

参数

params

UpdateUserReq

Future

UpdateUserRes

示例

deleteUser

Future<CloudBaseResponse<void>> auth.deleteUser(DeleteUserReq params)

Delete current user. Password is required for security verification.

参数

params

DeleteUserReq

Future

CloudBaseResponse<void>

示例

Identity Source Management

getUserIdentities

Future<GetUserIdentitiesRes> auth.getUserIdentities();

Get the list of identity sources bound to the current user.

参数

无参数

Future

GetUserIdentitiesRes

示例

linkIdentity

Future<LinkIdentityRes> auth.linkIdentity(LinkIdentityReq params)

Bind third-party identity source. Will redirect to third-party authorization page to complete binding.

参数

params

LinkIdentityReq

Future

LinkIdentityRes

示例

unlinkIdentity

Future<CloudBaseResponse<void>> auth.unlinkIdentity(UnlinkIdentityReq params)

Unbind third-party identity source.

参数

params

UnlinkIdentityReq

Future

CloudBaseResponse<void>

示例

Password Management

resetPasswordForEmail

Future<ResetPasswordForEmailRes> auth.resetPasswordForEmail(String emailOrPhone, {String? redirectTo})

Reset password via email or phone number. After calling, a verification code will be sent. You need to complete password reset through the returned updateUser callback.

参数

emailOrPhone

String

Email or phone number

redirectTo

String?

Redirect URL

Future

ResetPasswordForEmailRes

示例

resetPasswordForOld

Future<SignInRes> auth.resetPasswordForOld(ResetPasswordForOldReq params)

Reset password with old password.

参数

params

ResetPasswordForOldReq

Future

SignInRes

示例

reauthenticate

Future<ReauthenticateRes> auth.reauthenticate();

Re-authenticate. Send verification code to user's email or phone number. After verification, sensitive operations can be performed (such as setting a new password).

参数

无参数

Future

ReauthenticateRes

示例

Verification Management

getVerification

Future<GetVerificationRes> auth.getVerification(GetVerificationReq params)

Send verification code. Supports sending to email or phone number.

参数

params

GetVerificationReq

Future

GetVerificationRes

示例

verify

Future<VerifyRes> auth.verify(VerifyReq params)

Verify verification code (for email/phone verification).

参数

params

VerifyReq

Future

VerifyRes

示例

verifyOAuth

Future<SignInRes> auth.verifyOAuth(VerifyOAuthReq params)

Verify OAuth callback. Handle the callback after user authorization on third-party platform.

参数

params

VerifyOAuthReq

Future

SignInRes

示例

verifyOtp

Future<SignInRes> auth.verifyOtp(VerifyOtpParams params)

Verify OTP (one-time password). Used to verify the verification code sent by signInWithOtp or signUp.

参数

params

VerifyOtpParams

Future

SignInRes

示例

resend

Future<ResendRes> auth.resend(ResendReq params)

Resend verification code.

参数

params

ResendReq

Future

ResendRes

示例

getCaptchaToken

Future<GetCaptchaTokenRes> auth.getCaptchaToken()

Get CAPTCHA token. Used to get CAPTCHA verification token before sending verification code.

参数

无参数

Future

GetCaptchaTokenRes

示例

createCaptchaData

Future<CreateCaptchaDataRes> auth.createCaptchaData(CreateCaptchaDataReq params)

Create CAPTCHA verification data. Used to initialize CAPTCHA challenge.

参数

params

CreateCaptchaDataReq

Future

CreateCaptchaDataRes

示例

verifyCaptchaData

Future<VerifyCaptchaDataRes> auth.verifyCaptchaData(VerifyCaptchaDataReq params)

Verify CAPTCHA. Validate user's CAPTCHA response.

参数

params

VerifyCaptchaDataReq

Future

VerifyCaptchaDataRes

示例

clearCaptchaToken

Future<ClearCaptchaTokenRes> auth.clearCaptchaToken()

Clear CAPTCHA token. Clean up CAPTCHA state after verification.

参数

无参数

Future

ClearCaptchaTokenRes

示例

Data Model

getById

Future<GetByIdRes> app.data.model(collectionName).getById(String id)

Get a single record by ID.

参数

String

Record ID

Future

GetByIdRes

示例

get

Future<GetRes> app.data.model(collectionName).get([GetReq? params])

Query records with filters. Supports WHERE conditions, sorting, pagination, etc.

参数

params

GetReq?

Query parameters (optional)

Future

GetRes

示例

list

Future<ModelFindManyResponse> app.models.list({
  required String modelName,
  Map<String, dynamic>? filter,
  Map<String, dynamic>? select,
  int? pageSize,
  int? pageNumber,
  bool? getCount,
  List<Map<String, String>>? orderBy,
})

Query multiple records. Supports filter conditions, field selection, pagination, and sorting.

参数

modelName

String

Data model identifier

filter

Map<String, dynamic>?

Filter condition, format: {'where': {'field': {'\$eq': 'value'}}}

select

Map<String, dynamic>?

Field selection, format: {'\$master': true} or {'field': true}

pageSize

int?

Page size, default 10

pageNumber

int?

Page number, default 1

getCount

bool?

Whether to return total count

orderBy

List<Map<String, String>>?

Sorting, up to 3 fields, format: [{'field': 'desc'}]

Future

ModelFindManyResponse

示例

listSimple

Future<ModelFindManyResponse> app.models.listSimple({required String modelName, int? pageSize, int? pageNumber, bool? getCount})

Simple query for multiple records (GET request, only supports pagination parameters).

参数

modelName

String

Data model identifier

pageSize

int?

Page size

pageNumber

int?

Page number, default 1

getCount

bool?

Whether to return total count, default false

Future

ModelFindManyResponse

示例

create

Future<ModelCreateResponse> app.models.create({required String modelName, required Map<String, dynamic> data})

Create a single record.

参数

modelName

String

Data model identifier

data

Map<String, dynamic>

Record data

Future

ModelCreateResponse

示例

createMany

Future<ModelCreateManyResponse> app.models.createMany({required String modelName, required List<Map<String, dynamic>> data})

Batch create records.

参数

modelName

String

Data model identifier

data

List<Map<String, dynamic>>

List of records to create

Future

ModelCreateManyResponse

示例

update

Future<ModelUpdateDeleteResponse> app.models.update({required String modelName, required Map<String, dynamic> filter, required Map<String, dynamic> data})

Update a single record.

参数

modelName

String

Data model identifier

filter

Map<String, dynamic>

Filter condition

data

Map<String, dynamic>

Data to update

Future

ModelUpdateDeleteResponse

示例

updateMany

Future<ModelUpdateDeleteManyResponse> app.models.updateMany({required String modelName, required Map<String, dynamic> filter, required Map<String, dynamic> data})

Batch update records.

参数

modelName

String

Data model identifier

filter

Map<String, dynamic>

Filter condition

data

Map<String, dynamic>

Data to update

Future

ModelUpdateDeleteManyResponse

示例

upsert

Future<ModelUpsertResponse> app.models.upsert({required String modelName, required Map<String, dynamic> filter, Map<String, dynamic>? create, Map<String, dynamic>? update})

Create or update a single record (Upsert). If a matching record is found, it will be updated; otherwise, a new record will be created.

参数

modelName

String

Data model identifier

filter

Map<String, dynamic>

Filter condition

create

Map<String, dynamic>?

Data to create when record does not exist

update

Map<String, dynamic>?

Data to update when record already exists

Future

ModelUpsertResponse

示例

deleteById

Future<ModelUpdateDeleteResponse> app.models.deleteById({required String modelName, required String recordId})

Delete a single record by ID.

参数

modelName

String

Data model identifier

recordId

String

Record ID

Future

ModelUpdateDeleteResponse

示例

deleteRecord

Future<ModelUpdateDeleteResponse> app.models.deleteRecord({required String modelName, required Map<String, dynamic> filter})

Delete a single record by condition.

参数

modelName

String

Data model identifier

filter

Map<String, dynamic>

Filter condition

Future

ModelUpdateDeleteResponse

示例

deleteMany

Future<ModelUpdateDeleteManyResponse> app.models.deleteMany({required String modelName, required Map<String, dynamic> filter})

Batch delete records.

参数

modelName

String

Data model identifier

filter

Map<String, dynamic>

Filter condition

Future

ModelUpdateDeleteManyResponse

示例

mysqlCommand

Future<ModelMysqlCommandResponse> app.models.mysqlCommand({required String sqlTemplate, List<ModelMysqlParameter>? parameter, ModelMysqlConfig? config})

Execute MySQL commands. Supports parameterized queries.

参数

sqlTemplate

String

SQL statement, supports parameter placeholders {{ var }}

parameter

List<ModelMysqlParameter>?

SQL parameter list

config

ModelMysqlConfig?

Execution config (timeout, preparedStatements, dbLinkName)

Future

ModelMysqlCommandResponse

示例

Data Source Queries

getAggregateDataSourceList

Future<AggregateDataSourceListResponse> app.models.getAggregateDataSourceList({
  List<String>? idList,
  List<String>? nameList,
  int? pageSize,
  int? pageNumber,
  bool? getCount,
  List<Map<String, String>>? orderBy,
})

Query aggregate data source list (GET request, supports pagination and sorting).

参数

idList

List<String>?

Data source ID list

nameList

List<String>?

Data source name list

pageSize

int?

Page size, default 10

pageNumber

int?

Page number, default 1

getCount

bool?

Whether to return total count

orderBy

List<Map<String, String>>?

Sorting, format: [{'field': 'desc'}]

Future

AggregateDataSourceListResponse

示例

getDataSourceAggregateDetail

Future<DataSourceAggregateDetailResponse> app.models.getDataSourceAggregateDetail({
  String? datasourceId,
  String? dataSourceName,
  String? viewId,
  int? queryPublish,
  bool? queryModelRelation,
  String? dbInstanceType,
  String? databaseTableName,
})

Query aggregate data source detail by conditions. datasourceId and dataSourceName cannot both be empty.

参数

datasourceId

String?

Data source ID (cannot both be empty with dataSourceName)

dataSourceName

String?

Data source name (cannot both be empty with datasourceId)

viewId

String?

View ID

queryPublish

int?

Query published data source (0: preview, 1: published)

queryModelRelation

bool?

Whether to query relation

dbInstanceType

String?

DB instance type

databaseTableName

String?

Database table name

Future

DataSourceAggregateDetailResponse

示例

getDataSourceByTableName

Future<DataSourceByTableNameResponse> app.models.getDataSourceByTableName({required List<String> tableNames})

Query data source schema definition by database table name.

参数

tableNames

List<String>

Database table name list

Future

DataSourceByTableNameResponse

示例

getBasicDataSourceList

Future<BasicDataSourceListResponse> app.models.getBasicDataSourceList({
  List<String>? idList,
  List<String>? nameList,
  int? pageNum,
  int? pageSize,
  bool? queryAll,
  List<DataSourceQueryFilter>? queryFilterList,
  bool? onlyFlexDb,
})

Query basic data source list by conditions (POST request, supports filter conditions).

参数

idList

List<String>?

Data source ID list

nameList

List<String>?

Data source name list

pageNum

int?

Page number, default 1

pageSize

int?

Page size, default 10

queryAll

bool?

Whether to query all

queryFilterList

List<DataSourceQueryFilter>?

Query filter list

onlyFlexDb

bool?

Whether to query only flexdb type

Future

BasicDataSourceListResponse

示例

getBasicDataSource

Future<BasicDataSourceResponse> app.models.getBasicDataSource({
  String? datasourceId,
  String? dataSourceName,
  String? viewId,
  int? queryPublish,
  bool? queryModelRelation,
  String? dbInstanceType,
  String? databaseTableName,
})

Query basic data source info by conditions. datasourceId and dataSourceName cannot both be empty.

参数

datasourceId

String?

Data source ID (cannot both be empty with dataSourceName)

dataSourceName

String?

Data source name (cannot both be empty with datasourceId)

viewId

String?

View ID

queryPublish

int?

Query published data source (0: preview, 1: published)

queryModelRelation

bool?

Whether to query relation

dbInstanceType

String?

DB instance type

databaseTableName

String?

Database table name

Future

BasicDataSourceResponse

示例

getSchemaList

Future<DataSourceSchemaListResponse> app.models.getSchemaList({List<String>? dataSourceNameList})

Query all data source schemas in the environment. If no parameters are provided, all schemas are returned.

参数

dataSourceNameList

List<String>?

Data source name list (optional, query all if not provided)

Future

DataSourceSchemaListResponse

示例

getTableName

Future<DataSourceTableNameResponse> app.models.getTableName({String? dataSourceName})

Query the corresponding database table name by data source name.

参数

dataSourceName

String?

Data source name

Future

DataSourceTableNameResponse

示例

MySQL Database

query

Future<MySqlResponse> app.mysql.query({required String table, String? schema, String? instance, MySqlQueryOptions? options})

Query MySQL data. Supports field selection, pagination, sorting, and filter conditions.

Supported filter operators: eq (equal), neq (not equal), gt (greater than), gte (greater than or equal), lt (less than), lte (less than or equal), like (fuzzy match), in (in list), is (null check)

参数

table

String

Table name

schema

String?

Database name

instance

String?

Database instance identifier (requires schema)

options

MySqlQueryOptions?

Query options

Future

MySqlResponse

data可选List<Map<String, dynamic>>

Query result list

total可选int?

Total count (requires withCount set to true)

contentRange可选String?

Data range (from Content-Range response header)

statusCode可选int?

HTTP status code

statusText可选String?

HTTP status description

requestId可选String?

Request ID for error tracking

code可选String?

Error code (null on success)

message可选String?

Error message

isSuccess可选bool

Whether successful

示例

insert

Future<MySqlWriteResponse> app.mysql.insert({required String table, required dynamic data, String? schema, String? instance, bool? upsert, String? onConflict})

Insert data. Supports single and batch insert, as well as Upsert mode.

参数

table

String

Table name

data

dynamic

Insert data, single Map or batch List<Map>

schema

String?

Database name

instance

String?

Database instance identifier

upsert

bool?

Whether to enable Upsert mode (default false)

onConflict

String?

Upsert conflict field

Future

MySqlWriteResponse

示例

update (MySQL)

Future<MySqlWriteResponse> app.mysql.update({required String table, required Map<String, dynamic> data, required Map<String, String> filters, String? schema, String? instance})

Update MySQL data. WHERE condition is required.

参数

table

String

Table name

data

Map<String, dynamic>

Data to update

filters

Map<String, String>

WHERE condition (cannot be empty)

schema

String?

Database name

instance

String?

Database instance identifier

Future

MySqlWriteResponse

示例

delete (MySQL)

Future<MySqlWriteResponse> app.mysql.delete({required String table, required Map<String, String> filters, String? schema, String? instance})

Delete MySQL data. WHERE condition is required.

参数

table

String

Table name

filters

Map<String, String>

WHERE condition (cannot be empty)

schema

String?

Database name

instance

String?

Database instance identifier

Future

MySqlWriteResponse

示例

count

Future<MySqlCountResponse> app.mysql.count({required String table, Map<String, String>? filters, String? schema, String? instance})

Count MySQL data records.

参数

table

String

Table name

filters

Map<String, String>?

Filter conditions

schema

String?

Database name

instance

String?

Database instance identifier

Future

MySqlCountResponse

示例

Cloud Functions

callFunction

Future<FunctionResponse> app.callFunction({
  required String name,
  FunctionType? type,
  Map<String, dynamic>? data,
  HttpMethod? method,
  String? path,
  Map<String, String>? header,
  bool? parse,
})

Call cloud function. Supports both basic cloud functions and function-type cloud run.

参数

name

String

Function/service name

type

FunctionType?

Call type: FunctionType.function (default) / FunctionType.cloudrun

data

Map<String, dynamic>?

Request data

method

HttpMethod?

HTTP method (only valid for cloudrun type, default POST)

path

String?

HTTP path (only valid for cloudrun type, default /)

header

Map<String, String>?

HTTP headers (only valid for cloudrun type)

parse

bool?

Whether to parse return object (only valid for function type, default true)

Future

FunctionResponse

示例

Cloud Run

callContainer

Future<CloudRunResponse> app.callContainer({
  required String name,
  HttpMethod? method,
  String? path,
  Map<String, String>? header,
  Map<String, dynamic>? data,
})

Call cloud run container service. Supports custom HTTP method, path, and headers.

参数

name

String

Cloud run service name

method

HttpMethod?

HTTP request method (default GET)

path

String?

HTTP request path (default /)

header

Map<String, String>?

HTTP request headers

data

Map<String, dynamic>?

HTTP request body

Future

CloudRunResponse

示例

APIs

apis[name]

ApiMethodProxy app.apis[String apiName]

Call API gateway interface. Supports accessing API proxy objects via subscript operator for chained calls. Supports GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH methods.

参数

apiName

String

API name

ApiMethodProxy

API method proxy object, supports chained calls

ApiResponse

API response

示例

Cloud Storage

Cloud Storage module provides file upload, download, delete, copy, move and other operations.

Initialization

final app = await CloudBase.init(
  env: 'your-env-id',
  accessKey: 'your-access-key',
);

final storage = app.storage.from();

upload

Future<StorageResponse<StorageUploadResult>> storage.upload(
  String path,
  List<int> fileData, {
  StorageUploadOptions? options,
})

Upload file to cloud storage. This method will first get upload info, then upload file to COS, and finally return fileID.

参数

path

String

Cloud storage relative path, e.g. `images/photo.jpg`.

fileData

List<int>

File byte data.

options

StorageUploadOptions

Upload options.

data.id

String?

CloudBase fileID.

data.path

String?

Upload path.

data.fullPath

String?

File full path.

error

StorageError?

Error message.

示例

getUploadInfo

Future<StorageResponse<List<StorageUploadInfo>>> storage.getUploadInfo(
  List<String> paths,
)

Get file upload info. Returns upload URL and other info for client to directly upload files to COS.

参数

paths

List<String>

File path list (cloud storage relative path).

data

List<StorageUploadInfo>?

Upload info list.

error

StorageError?

Error message.

示例

getDownloadUrls

Future<StorageResponse<List<StorageDownloadInfo>>> storage.getDownloadUrls(
  List<String> fileIds, {
  int? expiresIn,
})

Get file download URLs.

参数

fileIds

List<String>

File ID list (full cloudObjectId, e.g. `cloud://envId.xxx/path/file.jpg`).

expiresIn

int?

Reserved parameter, current API does not support custom expiration time.

data

List<StorageDownloadInfo>?

Download info list.

error

StorageError?

Error message.

示例

createSignedUrl

Future<StorageResponse<String>> storage.createSignedUrl(
  String fileId,
  int expiresIn,
)

Create signed URL (temporary access link).

参数

fileId

String

Full fileID.

expiresIn

int

Expiration time (seconds).

data

String?

Signed URL.

error

StorageError?

Error message.

示例

createSignedUrls

Future<StorageResponse<List<StorageDownloadInfo>>> storage.createSignedUrls(
  List<String> fileIds,
  int expiresIn,
)

Batch create signed URLs.

参数

fileIds

List<String>

Full fileID list.

expiresIn

int

Expiration time (seconds).

data

List<StorageDownloadInfo>?

Download info list.

error

StorageError?

Error message.

示例

remove

Future<StorageResponse<List<StorageDeleteResult>>> storage.remove(
  List<String> fileIds,
)

Delete files.

参数

fileIds

List<String>

File ID list to delete (full fileID).

data

List<StorageDeleteResult>?

Delete result list.

error

StorageError?

Error message.

示例

copy

Future<StorageResponse<StorageCopyResult>> storage.copy(
  String fromPath,
  String toPath, {
  bool overwrite = true,
})

Copy file.

参数

fromPath

String

Source file path (relative path).

toPath

String

Target file path (relative path).

overwrite

bool

Whether to overwrite if target exists, default `true`.

data

StorageCopyResult?

Copy result.

error

StorageError?

Error message.

示例

copyBatch

Future<StorageResponse<List<StorageCopyResult>>> storage.copyBatch(
  List<Map<String, dynamic>> items,
)

Batch copy files.

参数

items

List<Map<String, dynamic>>

Copy item list, each item contains `srcPath` and `dstPath`.

data

List<StorageCopyResult>?

Copy result list.

error

StorageError?

Error message.

示例

move

Future<StorageResponse<StorageCopyResult>> storage.move(
  String fromPath,
  String toPath, {
  bool overwrite = true,
})

Move file (implemented by copy + removeOriginal).

参数

fromPath

String

Source file path (relative path).

toPath

String

Target file path (relative path).

overwrite

bool

Whether to overwrite if target exists, default `true`.

data

StorageCopyResult?

Move result.

error

StorageError?

Error message.

示例

StorageUploadOptions

Upload options:

Parameter	Type	Description
`cacheControl`	`String?`	Cache control, e.g. `max-age=3600`
`contentType`	`String?`	File MIME type, e.g. `image/jpeg`
`metadata`	`Map<String, dynamic>?`	Custom metadata
`upsert`	`bool`	Whether to overwrite existing file, default `true`

StorageUploadResult

Upload result:

Parameter	Type	Description
`id`	`String?`	CloudBase fileID
`path`	`String?`	Upload path
`fullPath`	`String?`	File full path

StorageUploadInfo

Upload info:

Parameter	Type	Description
`path`	`String?`	File path
`uploadUrl`	`String?`	Upload URL
`token`	`String?`	Upload token
`authorization`	`String?`	Upload authorization
`fileId`	`String?`	File ID
`cosFileId`	`String?`	COS file ID
`code`	`String?`	Error code
`message`	`String?`	Error message

StorageDownloadInfo

Download info:

Parameter	Type	Description
`fileId`	`String?`	File ID
`downloadUrl`	`String?`	Download URL
`code`	`String?`	Error code (on partial failure)
`message`	`String?`	Error message (on partial failure)

StorageDeleteResult

Delete result:

Parameter	Type	Description
`fileId`	`String?`	File ID
`code`	`String?`	Error code (on partial failure)
`message`	`String?`	Error message (on partial failure)

StorageCopyResult

Copy result:

Parameter	Type	Description
`cloudObjectId`	`String?`	Cloud file ID of copied object
`code`	`String?`	Error code (on partial failure)
`message`	`String?`	Error message (on partial failure)

StorageResponse<T>

Storage response:

Parameter	Type	Description
`data`	`T?`	Response data
`error`	`StorageError?`	Error message

StorageError

Storage error:

Parameter	Type	Description
`code`	`String?`	Error code
`message`	`String?`	Error message
`requestId`	`String?`	Request ID

Basic Usage Example​

Authentication​

signUp​

参数

返回

示例

signInAnonymously​

参数

返回

示例

signInWithPassword​

参数

返回

示例

signInWithOtp​

参数

返回

示例

signInWithOAuth​

参数

返回

示例

signInWithIdToken​

参数

返回

示例

signInWithCustomTicket​

参数

返回

示例

Session Management​

getSession​

参数

返回

示例

refreshSession​

参数

返回

示例

setSession​

参数

返回

示例

signOut​

参数

返回

示例

onAuthStateChange​

参数

返回

示例

getClaims​

参数

返回

示例

User Management​

getUser​

参数

返回

示例

refreshUser​

参数

返回

示例

updateUser​

参数

返回

示例

deleteUser​

参数

返回

示例

Identity Source Management​

getUserIdentities​

参数

返回

示例

linkIdentity​

参数

返回

Basic Usage Example

Authentication

signUp

signInAnonymously

signInWithPassword

signInWithOtp

signInWithOAuth

signInWithIdToken

signInWithCustomTicket

Session Management

getSession

refreshSession

setSession

signOut

onAuthStateChange

getClaims

User Management

getUser

refreshUser

updateUser

deleteUser

Identity Source Management

getUserIdentities

linkIdentity

unlinkIdentity

Password Management

resetPasswordForEmail

resetPasswordForOld

reauthenticate

Verification Management

getVerification

verify

verifyOAuth

verifyOtp

resend

getCaptchaToken

createCaptchaData

verifyCaptchaData

clearCaptchaToken

Data Model

getById

get

list

listSimple