README

DSYNC的实时同步PHP SDK

概述

DSYNC PHP SDK是开发者连接第三方系统与DSYNC平台的快速入门包。通过基于SDK构建外部连接器，您的系统将能够自动与DSYNC平台上已存在的各种系统、API和数据库进行近乎实时数据交换。

DSYNC与第三方系统之间的近乎实时数据交换使用安全的http协议。您需要构建的外部连接器本质上是一个RESTful API，能够仅从DSYNC平台接收和发送http请求。一些系统可能已有现有API，您可以简单扩展并调整到DSYNC规范，或者您可能需要从头开始构建。

您无需担心不同系统可能具有的所有不同API – 这是DSYNC的责任。您需要构建的是您系统与DSYNC平台之间的通信通道。

身份验证

DSYNC平台使用API密钥与第三方系统进行通信。您可以在“我的账户”部分创建新的API密钥。将此密钥视为密码。任何拥有密钥的人都可以代表您发送/接收数据。由于API密钥没有设置过期时间，强烈建议定期轮换API密钥以防止未经授权的访问。

必须将API密钥与您发送给DSYNC平台的每个请求一起发送。您的连接器必须能够存储此密钥并在请求中将它作为‘Auth-Token’头信息发送。如果您未能发送有效的API密钥，DSYNC平台将响应401未授权。当您在请求上设置授权令牌时，DSYNC PHP SDK将为您添加头信息。

术语表

数据布局

定义一个或多个端点和它们所有相关字段的JSON格式的模式。由您在第三方系统中生成并发送到DSYNC。

为了使DSYNC正确在画布上构建和显示新的系统，您的连接器生成的数据布局必须定义至少一个实体，并且实体必须至少有一个字段（例如，具有SKU字段的商品实体）。

端点/实体

第三方系统内的单个资源/对象。（例如，产品）

字段

实体的属性（例如，SKU）

API密钥

（又称认证令牌）用于在第三方系统与DSYNC平台之间进行http请求认证的密码

实体令牌

（又称端点令牌）第三方系统生成并发送到DSYNC数据布局的唯一标识符。系统范围 – 必须是唯一的。

Treekey

唯一标识实体模式中单个字段的定位。使用对象点表示法。实体范围 – 必须是唯一的。

入门指南

创建DSYNC账户（https://www.dsync.com/pricing）
在创建的账户中创建一个认证令牌以用于SDK
创建可消费的端点以生成DSYNC应用程序的数据布局（见下文）
在您的DSYNC仪表板上安装DIY系统

完整的账户设置说明可以在开发者门户中找到（https://dsyncsdk.docs.apiary.io/reference/diy-connector）

API文档

完整的API文档可以在开发者门户中找到（https://dsyncsdk.docs.apiary.io/reference/source）

安装

使用composer安装此包

composer require dsync/php-sdk

请求

使用RealtimeRequest对象创建请求。在发出请求之前，您可以在数据中加入身份验证和端点令牌（在datalayout中设置），以及数据。

实时 "创建" 请求示例

use Dsync\PhpSdk\Endpoint\RealtimeRequest;
use Dsync\PhpSdk\Exception\RealtimeRequestException;

$data = ['foo' => 'bar'];

// create a new realtime request object with your authorization token, endpoint token and data
$request = new RealtimeRequest('yourAuthToken', 'yourEndpointToken', $data);

try {
    // send a create request
    $result = $request->create();
} catch (RealtimeRequestException $e) {
    // do something if there is an exception
}

实时 "更新" 请求示例

use Dsync\PhpSdk\Endpoint\RealtimeRequest;
use Dsync\PhpSdk\Exception\RealtimeRequestException;

$data = ['foo' => 'foo'];

// create a new realtime request object
$request = new RealtimeRequest();

// set your authorization token, endpoint token and data on the request
$request
    ->setAuthToken('yourAuthToken')
    ->setEntityToken('yourEndpointToken')
    ->setData($data);

try {
    // send an update request
    $result = $request->update();
} catch (RealtimeRequestException $e) {
    // do something if there is an exception
}

实时 "删除" 请求示例

'删除'请求需要主键（setEntityId），这在datalayout中已定义，因为这个方法不发送正文。

use Dsync\PhpSdk\Endpoint\RealtimeRequest;
use Dsync\PhpSdk\Exception\RealtimeRequestException;

// create a new realtime request object with your authorization token and endpoint token
$request = new RealtimeRequest('yourAuthToken', 'yourEndpointToken');

// set your primary key for the entity you wish to delete as defined by the datalayout
$request->setEntityId('primaryKeyAsDefinedInDatalayout');

try {
    // send a delete request
    $result = $request->delete();
} catch (RealtimeRequestException $e) {
    // do something if there is an exception
}

响应

所有实时方法在出错时将抛出RealtimeRequestException，在成功时返回数据数组。

Datalayout工具

PHP SDK附带一些工具，用于为每个端点生成布局和令牌。DSYNC应用程序必须能够消费您生成的datalayout。有关详细信息，请参阅开发者门户（https://dsyncsdk.docs.apiary.io/#reference/destination/data-layout/get-data-layout）

生成datalayout数组的示例

首先构建字段并将它们添加到端点对象中。在运行'generate'方法之前，将端点对象添加到datalayout对象中。

use Dsync\PhpSdk\Utils\Generator\Datalayout;
use Dsync\PhpSdk\Utils\Generator\Endpoint;
use Dsync\PhpSdk\Utils\Generator\Field;

// create a new field object
$field = new Field();

// set field information
// a list of field type constants can be found in the Dsync\PhpSdk\Utils\Generator\Field class
$field
    ->setPrimaryKey(true)
    ->setRequired(true)
    ->setTreekey('product.sku')
    ->setDescription('A product SKU')
    ->setName('sku')
    ->setType(Field::TYPE_TEXT);

// create a new endpoint object
$endpoint = new Endpoint();

// set endpoint information and add all fields using the addField method
$endpoint
    ->setEntityName('product')
    ->setTreekey('product')
    ->setEntityToken('source-1-product-b5503a0ae5f3bc01b6a2da68afd33305')
    ->setEndpointUrl('/entity/product')
    ->addField($field);

// finally create a new datalayout object
$datalayout = new Datalayout();

// add all endpoints using the addEndpoint method and call the generate method 
// to create the datalayout array
$datalayoutArray = $datalayout
    ->addEndpoint($endpoint)
    ->generate();

如果使用Symfony或类似工具，请将生成的数组添加到响应中

$response = new JsonResponse();

$responseArray = [
    'status' => 200,
    'message' => 'OK',
    'detail' => '',
    'data' => $datalayoutArray
];

$response->setData($responseArray);

return $response;

生成实体令牌的示例

use Dsync\PhpSdk\Utils\Generator\Endpoint;
use Dsync\PhpSdk\Utils\Generator\EntityToken;

$entityTokenClass = new EntityToken();

// generate the entity token using an endpoint name as reference
$entityToken = $entityTokenClass->generateEntityToken('product');

$endpoint = new Endpoint();

// set the entity token on the endpoint object
$endpoint
    ->setEntityName('product')
    ->setTreekey('product')
    ->setEntityToken($entityToken)
    ->setEndpointUrl('/entity/product')
    ->addField($field);

// save $entityToken to make requests at a later time

运行开发者编码标准和测试

使用composer安装包

$ composer install

安装Ant（https://ant.apache.ac.cn/）

$ apt-get install ant

运行Ant

$ ant

dsync / php-sdk

维护者

详细信息