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'。

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

注意：营销云API使用特殊的配置方法来创建/更新/删除属性定义和角色对象。为了标准化使用，DataProBoston SDK通过通用的创建/更新/删除方法支持这些操作，并在内部调用配置方法。

更新和删除方法。

方法参数

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（布尔值）。仅适用于检索方法。
仅检索自上次检索调用以来添加/修改的对象，这些对象的属性和过滤器相同。

返回值

检索方法返回 \stdClass 对象数组，检索一个方法返回 \stdClass 对象。如果没有结果，检索一个方法将返回 null。如果有超过1个结果，检索一个方法将抛出 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);

检索更多方法

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

方法参数

requestId（字符串或null）。如果没有指定，将使用 getLastRequestId() 中的一个。在这种情况下，在遍历结果时无法调用其他方法。要能够调用其他方法，应使用 getLastRequestId() 获取 requestId 并将其传递给 retrieveMore()。

返回值

与检索方法中的相同。

用法

// 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。如果在多个对象模式的 Create / Update / Delete / Perform 方法中请求API之后发生错误，则会抛出。

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

getErrors()。返回一个错误数组，其中每个错误是包含消息（字符串）和代码（int）的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。有关完整的版权和许可信息，请查看与此源代码一起分发的LICENSE文件。

bbathel12 / marketing-cloud-php-sdk

维护者

详细信息

README

要求

安装

基本用法

文档

AuthClient

构造函数参数

SoapClient

构造函数参数

创建方法

方法参数

返回值

更新和删除方法。

方法参数

返回值

执行方法

方法参数

返回值

检索和检索一个方法

方法参数

返回值

可用的过滤器运算符

用法

检索更多方法

方法参数

返回值

用法

异常处理

用法

实用方法

运行测试

问题和支持

版权和许可