README

DataProBoston Salesforce Marketing Cloud（原名ExactTarget）PHP SDK。

##概述## DataProBoston SDK提供了一种简洁、易于与Salesforce Marketing Cloud API交互的方式。目前仅支持SOAP API，未来版本将添加REST API支持。

需求

PHP版本 5.6.x, 7.x

扩展

soap
curl [推荐]

DataProBoston SDK使用Guzzle作为HTTP客户端，其需求可以在 http://docs.guzzlephp.org/en/latest/overview.html#requirements 上找到。

安装

composer require dataproboston/marketing-cloud-php-sdk

基本用法

use DataProBoston\MarketingCloud\AuthClient;
use DataProBoston\MarketingCloud\SoapClient;

$authClient = new AuthClient([
    'clientId' => CLIENT_ID,
    'clientSecret' => CLIENT_SECRET,
]);

$client = new SoapClient(null, [], $authClient);

// Create object
$listId = $client->create('List', [
    'ListName' => 'test',
]);

// Create mulpiple objects in one call - $listsIds is an array of objects' identifiers.
$listsIds = $client->create('List', [
    [
        'ListName' => 'test5',
    ],
    [
        'ListName' => 'test6',
    ],    
]);

// Array of properties to retrieve.
$properties = ['ListName'];

$filter = ['ID', '=', $listId];

// Retrieve one object - $list is an object of \stdClass
$list = $client->retrieveOne('List', $properties, $filter);

// Retrieve collection of objects - $lists is an array of objects of \stdClass
$lists = $client->retrieve('List', $properties);

$client->update('List', [
    'ID' => $listId,
    'ListName' => 'test2',
]);

$client->delete('List', [
    'ID' => $listId,
]);

// Delete mulpiple objects in one call
$client->delete('List', [
    [
        'ID' => $listsIds[0],
    ],
    [
        'ID' => $listsIds[1],
    ],    
]);

除了低级别的SoapClient和RestClient，DataProBoston SDK还提供高级的Driver抽象，它提供了有用的高级方法。
Driver也可以用作示例的来源。

使用Driver发送电子邮件活动的示例工作流程

use DataProBoston\MarketingCloud\Driver;

$driver = new Driver($soapClient);

$listId = $driver->createList('Test campaign');

$driver->createSubscribers(['youremail@gmail.com'], $listId);

$emailId = $driver->createEmail('Test campaign', 'Test campaign subject', 'Test campaign body');

$senderProfileId = $driver->createSenderProfile('Test sender profile', 'Sender name', 'senderemail@gmail.com');

// Assumed that API account has DeliveryProfile with CustomerKey value 'Default'.
$sendClassificationId = $driver->createSendClassification('Test send classification', $senderProfileId, 'Default');

$emailSendDefinitionId = $driver->createEmailSendDefinition($listId, $emailId, $sendClassificationId);

$sendId = $driver->sendEmailSendDefinition($emailSendDefinitionId);

文档

AuthClient

AuthClient被提取为单独的类，以便在SoapClient和RestClient之间共享（将在未来版本中提供）。

构造函数参数

options (数组)。可用选项
- clientId (字符串)。必需。
- clientSecret (字符串)。必需。
- authTokenMinExpirationTime (整数)。令牌到期前剩余的最小时间（秒）将导致令牌刷新。默认值 - 30。
- timeout (浮点数)。请求超时（秒）。默认值 - 10。
- sslVerifyPeer (布尔值|字符串)。启用/禁用SSL证书验证。请参阅 http://docs.guzzlephp.org/en/latest/request-options.html#verify。默认值 - false。

SoapClient

构造函数参数

wsdl (字符串)。WSDL文件的绝对路径。如果为null，则使用捆绑的WSDL（取决于wsdlInstance选项）。
options (数组)。可用选项
- wsdlInstance (字符串)。要使用的捆绑WSDL实例。可用实例：'main', 's4', 's6', 's7', 'test'。默认值 - 'main'。
- timeout (浮点数)。请求超时（秒）。默认值 - 60。
- sslVerifyPeer (布尔值|字符串)。启用/禁用SSL证书验证。请参阅 http://docs.guzzlephp.org/en/latest/request-options.html#verify。默认值 - false。
authClient (AuthClient)。

创建方法

方法参数

objectType (字符串)。
object (数组)。对象参数可以是
- 对象属性关联数组（单对象模式）。
- 对象属性关联数组的数字数组（多对象模式）。
upsert（布尔值）。只有一些对象支持upsert。

返回值

对象标识符或对象标识符数组，具体取决于$object参数。在多对象模式下，返回数组中的索引将对应于$object参数中的索引。

在出错时，方法将抛出一个DataProBoston\MarketingCloud\Exception\ClientException接口的实例。

有关更多信息，请参阅“异常处理”。

注意：Marketing Cloud API使用两种类型的对象标识符

旧版标识符（ID，整数）。

实际标识符（ObjectID，字符串）。

官方文档不提供有关每个对象使用的标识符类型的详细信息。

创建方法会自动返回正确的标识符。

要更新/删除/按标识符筛选，应正确指定其属性名称（'ID'或'ObjectID'）。目前，可以通过创建方法的返回值简单确定属性名称 - 如果是整数，则属性名称为'ID'；如果是字符串，则属性名称为'ObjectID'。

计划在未来的版本中自动选择正确的标识符属性。

注意：Marketing Cloud API使用特殊的Configure方法来创建/更新/删除PropertyDefinition和Role对象。为了标准化使用，DataProBoston SDK通过通用创建/更新/删除方法提供对这些操作的支持，并内部调用Configure方法。

更新和删除方法。

方法参数

objectType (字符串)。
对象（数组）。与创建方法中的格式相同。
对于更新方法，应指定对象标识符属性以及要更新的对象属性。
对于删除方法，只需要对象标识符属性。
使用其他对象的属性而不是标识符来选择更新/删除的对象目前尚未确定。

返回值

不返回任何值。

在出错时，方法将抛出一个DataProBoston\MarketingCloud\Exception\ClientException接口的实例。

有关更多信息，请参阅“异常处理”。

执行方法

方法参数

objectType (字符串)。
对象（数组）。与创建方法中的格式相同。
操作（字符串）。在大多数情况下使用字符串'start'，请参阅https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/perform.htm

返回值

任务标识符或任务标识符数组，具体取决于$object参数。在多对象模式下，返回数组中的索引将对应于$object参数中的索引。

在出错时，创建方法将抛出一个DataProBoston\MarketingCloud\Exception\ClientException接口的实例。

有关更多信息，请参阅“异常处理”。

检索和检索一个方法

方法参数

objectType (字符串)。
属性（数组）。要检索的对象的属性。
过滤器（数组）。3元素数字数组，有两种可能的格式
- 简单条件：[$property, $operator, $value]
- 逻辑条件：[$leftCondition, $operator, $rightCondition]。
  如果操作符是'and'或'or'，则应用。
  $leftCondition / $rightCondition自身可以是简单条件或嵌套逻辑条件。
  在过滤器值中，日期应以\DateTime对象表示。
sinceLastBatch（布尔值）。仅适用于检索方法。
仅检索自上次检索调用以来添加/修改的具有相同属性和筛选器的对象。

返回值

Retrieve方法的\stdClass对象数组，以及RetrieveOne方法的\stdClass对象。如果没有结果，RetrieveOne方法将返回null。如果有多个结果，RetrieveOne方法将抛出ResponseException异常。

可用的筛选器运算符

=
!=
>
<
>=
<=
isNull
!isNull
between
in
like
and
or

用法

$sendId = 11111;
$startDate = new \DateTime();
$finishDate = new \DateTime();
$startDate->modify('-1 day');

$properties = ['SubscriberKey', 'EventDate'];

$filter = [
    ['SendID', '=', $sendId],
    'and',
    ['EventDate', 'between', [$startDate, $finishDate]]
];

$sentEvents = $client->retrieve('SentEvent', $properties, $filter);

RetrieveMore方法

Retrieve方法在一次调用中返回最多2500个对象。为了检索所有对象，应检查是否有更多结果使用hasMoreResults()方法，如果有，则调用retrieveMore()。

方法参数

requestId (string|null)。如果没有指定，则使用getLastRequestId()的值。在这种情况下，在迭代结果时不能调用其他方法。为了能够调用其他方法，应使用getLastRequestId()获取requestId并将其传递给retrieveMore()。

返回值

与Retrieve方法相同。

用法

// without any other method calls
$subscribers = $client->retrieve('Subscriber', ['ID']);    
while ($client->hasMoreResults()) {        
    $subscribers = $client->retrieveMore();
}


// with other method calls
$subscribers = $client->retrieve('Subscriber', ['ID']);    
$requestId = $client->getLastRequestId();
while ($client->hasMoreResults()) {        
    $subscribers = $client->retrieveMore($requestId);
}

异常处理

DataProBoston SDK抛出的异常是DataProBoston\MarketingCloud\Exception\ClientException接口的实例。

可用的异常列表

RequestException。如果在请求API之前发生错误，将抛出。
ResponseException。如果在请求API之后发生错误，将抛出。
- MultipleModeResponseException。如果在请求API后，在多个对象模式下的Create / Update / Delete / Perform方法中发生错误，将抛出。

在多个对象模式下，某些对象可以成功处理，而某些对象有错误。如果至少有一个错误，DataProBoston SDK将抛出MultipleModeResponseException异常。此异常有两个有用的方法

getErrors()。返回错误数组，其中每个错误是包含消息（字符串）和代码（整数）的2元素数组。索引对应于SoapClient方法调用中$object参数的索引。
getCreatedObjectsIdentifiers()。返回与Create / Perform方法的返回值相同的标识符数组。索引对应于SoapClient方法调用中$object参数的索引。

用法

try {
    $client->create('List', [
        [
            'ListName' => 'test1',
        ],
        [
            'ListName' => 'test2',
        ],    
    ]);  
} catch (MultipleModeResponseException $e) {
    // errors
    $errors = $e->getErrors();
    
    // successfully created objects identifiers
    $identifiers = $e->getCreatedObjectsIdentifiers();
}

实用方法

describe(objectType)。返回所有objectType属性的数组(\stdClass对象)。
describeSubscriberAttributes()。返回所有Subscriber对象属性（"扩展属性"）的数组(\stdClass对象)。
systemStatus()。返回系统状态字符串："OK"|"InMaintenance"|"UnplannedOutage"。
versionInfo(includeVersionHistory)。返回API版本信息(\stdClass对象)。
requestEndpoint()。返回API端点URL（字符串）。
getFilterOperators()。返回可用的筛选器运算符数组。
getLastRequestId()。返回最后一个请求ID（字符串）。
hasMoreResults()。指示检索请求是否有更多结果（布尔值）。

execute。仅适用于检索用户令牌

  $requests = [
      'Name' => 'GetUserToken',
  ];

  $response = $client->execute($requests);

运行测试

将 phpunit.xml.dist 复制到 phpunit.xml，并在 <php> 部分提供您的设置（clientId、clientSecret 等）。

问题和支持

如有任何问题/疑问/建议，请随时在 Github 上联系我们。

版权和许可证

遵循 MIT 许可证。有关完整的版权和许可信息，请查看与此源代码一起分发的 LICENSE 文件。

dataproboston / marketing-cloud-php-sdk

维护者

详细信息

README

需求

安装

基本用法

文档

AuthClient

构造函数参数

SoapClient

构造函数参数

创建方法

方法参数

返回值

更新和删除方法。

方法参数

返回值

执行方法

方法参数

返回值

检索和检索一个方法

方法参数

返回值

可用的筛选器运算符

用法

RetrieveMore方法

方法参数

返回值

用法

异常处理

用法

实用方法

运行测试

问题和支持

版权和许可证