Flutter通信连接插件daktela_connector的使用

Daktela V6 Dart Connector

Daktela V6 Dart Connector 是一个库，使您的 Dart/Flutter 应用程序能够连接到您的 Daktela V6 REST API。此连接器要求您已经购买、安装并准备好使用 Daktela Contact Centre 应用程序。Daktela Contact Centre 是一个应用程序，允许通过各种渠道（例如电话、电子邮件、网络聊天、短信或社交媒体）处理所有客户通信。

设置

连接器需要以下先决条件：

• 实例 URL 的形式为 https://URL/
• 每次访问 Daktela V6 REST API 所需的访问令牌，基于所需的权限

使用方法

DaktelaConnector 是一个单例类，允许您在 Daktela 服务器上发送 CRUD 请求。 它需要一个配置类 DaktelaConnectorConfig 的实例，其中必须至少指定实例 URL，并且大多数情况下可能还需要设置用户的访问令牌。其他选项如下所示。

DaktelaConnectorConfig

DaktelaConnector 的配置选项：

• url - 实例的 URL（必需），例如 ‘my.daktela.com’，
• accessToken - 用户用于身份验证的访问令牌，
• timeout - 请求超时时间（默认：10 秒），
• longPollingTimeout - 如果实现自定义应用拉取数据工作者，可以设置长轮询请求的超时时间（默认：30 秒），
• userAgent - 应用的用户代理，
• cookieAuth - 允许您通过 cookie 对请求进行身份验证（默认值为 false，在这种情况下，访问令牌将添加到请求的查询参数中），
• logger - DaktelaLogger 的实例，允许您实现自定义日志记录方法，
• errors - DaktelaErrorMessages 的实例，用于覆盖连接器定义的默认错误消息。

var logger = DaktelaLogger(
  callback: (String message, {Object? error, DaktelaLogLevel? logLevel, StackTrace? stackTrace}) {
    print(message); // 打印消息
    if (error != null) {
      print('Error:  $error'); // 打印错误信息
    }
    if (stackTrace != null) {
      print('StackTrace:  $stackTrace'); // 打印堆栈跟踪
    }
  },
);

var config = DaktelaConnectorConfig(
  url: 'my.daktela.com', // 实例 URL
  accessToken: 'e10adc3949ba59abbe56e057f20f883e', // 访问令牌
  userAgent: 'MyDaktelaClient-1.0.0', // 用户代理
  cookieAuth: true, // 使用 cookie 身份验证
  logger: logger, // 自定义日志记录器
  errors: DaktelaErrorMessages(general: 'Ooops'), // 自定义错误消息
);

DaktelaConnector

该类允许您调用 GET、POST、PUT 或 DELETE 请求。有两个必要步骤：

1. 通过 getter instance 获取 DaktelaConnector 的实例，
2. 通过 setter config 设置 DaktelaConnectorConfig 的实例。

然后您可以调用 get、post、put 和 delete 方法，这些方法使用标准的 HTTP 方法。 方法参数：

• endpoint - 端点名称（必需），例如 ‘tickets.json’
• query - 查询参数的映射（Map<String, dynamic>），建议使用 DaktelaQueryMap 构建请求的查询，
• payload - POST 或 PUT 请求的有效负载映射（Map<String, dynamic>），
• nestedDecoding - 响应解码标志（默认为 true，表示标准响应解码），
• internalEndpoint - 标志，用于使用 /internal 端点前缀而不是标准的 /api/v6（默认：false），
• longPollingRequest - 标志，用于使用长轮询请求超时（默认：false）。

来自服务器的标准响应是 DaktelaResponse 的实例，具有属性 statusCode（int）、result（dynamic）和 total（int?）。

请求可能会抛出异常 DaktelaException 或其子类（DaktelaUnauthorizedException、DaktelaNotFoundException）。

var connector = DaktelaConnector.instance..config = config;

String? accessToken;
try {
  var r = await connector.post('login.json', payload: {
    'username': 'user_1',
    'password': 'password_1',
    'only_token': '1',
  });
  accessToken = r.result as String; // 获取访问令牌
} catch (e) {
  print(e); // 打印异常
}

排序、分页和过滤

在处理较大的数据量时，可以使用分页、排序、过滤和字段投影。可以通过 DaktelaQueryMap 及其静态方法 build 创建查询参数的映射，参数包括：

• DaktelaFilter? filter - 过滤定义类，由原子字段部分（DaktelaFilterField 的实例）组成，
• DaktelaSort? sort - 简单的类，用于按一个或多个字段对数据进行排序。它也由原子部分组成（DaktelaSort 的实例），
• DaktelaPagination? pagination - 当您想批量动态加载数据时很有用，
• String? search - 对于某些端点，可以使用全文搜索，
• List<String>? fields - 允许您指定应返回的模型字段。

请求 Tickets 模型的复杂示例，带有查询参数：

var r = await connector.get(
  'tickets.json',
  queryParameters: DaktelaQueryMap.build(
      pagination: DaktelaPagination(take: 3), // 分页
      fields: ['name', 'title', 'category', 'user'], // 返回字段
      filter: DaktelaFilter.simple(DaktelaFilterField(field: 'stage', operator: 'eq', value: ['CLOSE'])), // 过滤条件
      sort: DaktelaSort.simple(DaktelaSortField(field: 'edited', direction: 'desc')), // 排序
  ),
);

示例

请参阅 example/example.dart 中的简单使用示例。在那里您会找到：

• 通过 DaktelaLogger 定制日志记录，
• 获取访问令牌（登录），
• 在 tickets.json 端点上的请求以及 DaktelaQueryMap 的示例用法。

import 'package:daktela_connector/daktela_connector.dart';

void main() async {
  const instance = 'mydaktela.daktela.com'; // 实例 URL

  var logger = DaktelaLogger(
    callback: (String message, {Object? error, DaktelaLogLevel? logLevel, StackTrace? stackTrace}) {
      print(message); // 打印消息
      if (error != null) {
        print('Error:  $error'); // 打印错误信息
      }
      if (stackTrace != null) {
        print('StackTrace:  $stackTrace'); // 打印堆栈跟踪
      }
    },
  );

  var config = DaktelaConnectorConfig(
    url: instance, // 配置实例 URL
  );

  var connector = DaktelaConnector.instance..config = config;

  String? accessToken;
  try {
    // 获取用户的访问令牌
    var r = await connector.post('login.json', payload: {
      'username': 'user_1',
      'password': 'password_1',
      'only_token': '1',
    });
    accessToken = r.result as String;
    print(r.result); // 打印访问令牌
  } on DaktelaException catch (e) {
    print(e); // 打印异常
  }

  if (accessToken != null) {
    config = DaktelaConnectorConfig(
      url: instance,
      accessToken: accessToken, // 设置访问令牌
      logger: logger, // 设置日志记录器
      errors: DaktelaErrorMessages(general: 'Ooops'), // 设置错误消息
    );

    connector = DaktelaConnector.instance..config = config;
    try {
      // 获取用户的静态信息
      var r = await connector.get('whoim.json');
      print(r.result['user']['title']); // 打印用户标题

      // 获取最近 3 条未关闭的工单（按编辑时间降序排列）
      r = await connector.get(
        'tickets.json',
        queryParameters: DaktelaQueryMap.build(
          pagination: DaktelaPagination(take: 3), // 分页
          fields: ['name', 'title', 'category', 'user'], // 返回字段
          filter: DaktelaFilter.simple(DaktelaFilterField(field: 'stage', operator: 'eq', value: ['CLOSE'])), // 过滤条件
          sort: DaktelaSort.simple(DaktelaSortField(field: 'edited', direction: 'desc')), // 排序
        ),
      );
      print('Tickets count: ${r.total}'); // 打印工单总数
      (r.result as List).forEach((e) {
        print('Ticket(name=${e['name']}, title=${e['title']}, category=${e['category']['title']}), user=${e['user'] != null ? e['user']['title'] : 'null'}'); // 打印每个工单的信息
      });
    } on DaktelaException catch (e) {
      print(e); // 打印异常
    }
  }
}