README

此软件包提供了一个用于Autotask REST API的PHP API客户端。它是强类型化的，并且在使用任何具有自动完成的智能IDE中与这些类一起工作是一种美妙的体验。

安装方法

运行 composer require anteris-dev/autotask-client

要求

PHP ^7.4 以充分利用PHP的类型转换。
Guzzle ^6.3 以对Autotask API进行请求。

Discord

加入Anteris-Dev Discord，与其他此包的用户保持联系！

入门

客户端包装器

为了方便起见，有一个客户端包装器，允许您轻松与每个Autotask服务交互。这可以通过以下方式创建。

<?php

$client = new Anteris\Autotask\Client($apiUser, $apiSecret, $integrationCode, $baseUrl);

从这里，您可以通过引用其类方法（如下所示）使用任何服务。类包装器缓存每个服务的实例化，使其更高效。

注意：类方法命名为其端点名称的驼峰式版本（例如，Contacts是contacts()，ContactGroups是contactGroups()）。

<?php

$client->contacts();

要找到您公司的基本URL，请访问https://webservices.autotask.net/atservicesrest/v1.0/zoneInformation?user={{ apiUser }}，其中{{ apiUser }}等于您的API用户的用户名。

绕过客户端包装器

如果您只与一个或两个Autotask端点交互，您可能希望绕过客户端包装器。您可以通过以下方式执行此操作。

<?php

// Note that we are using the HttpClient, not the wrapper Client.
$client = new Anteris\Autotask\HttpClient($apiUser, $apiSecret, $integrationCode, $baseUrl);

$contactEndpoint = new Anteris\Autotask\API\Contacts\ContactService($client);
$ticketEndpoint  = new Anteris\Autotask\API\Tickets\TicketService($client);

与端点交互

每个服务都有几种方法可以帮助您与端点交互。以下列出了这些方法。如果执行请求时出现问题，CRUD操作将抛出异常。

如果端点不支持某种操作（例如创建资源），则类将不具有该方法。要检查端点是否支持方法，请查看Autotask API文档。我们在资源部分留下了一个链接。

create( $resource )

允许创建新项目的端点具有create()方法。它接受一个实体。其使用示例可能如下所示。

<?php

$contact = new Anteris\Autotask\API\Contacts\ContactEntity([
    'id' => 0, // Autotask requires that new entities have an ID of 0
    'companyID' => 123,
    'firstName' => 'New',
    'lastName' => 'User',
    'isActive' => 1,
]);

// This sends the create request
$client->contacts()->create( $contact );

deleteById( int $id )

允许删除项目的端点具有deleteById()方法。它接受一个整数，应该是Autotask中资产的字段ID。其使用示例可能如下所示。

<?php

$client->contacts()->deleteById(1);

findById( int $id )

可以查询的端点具有findById()方法。它接受一个整数，应该是Autotask中资产的字段ID。其使用示例可能如下所示。

<?php

// Looks finds a contact with the ID of 1.
// Alternatively use $contactEndpoint->findById(1);
$contact = $client->contacts()->findById(1);

// This returns an object with all the properties of a contact
echo $contact->firstName;

getEntityFields()

所有端点都可以查询基本元数据。此方法返回资源所具有的字段及其数据类型的规范。有关更多信息，我们建议您查看Autotask文档。

getEntityInformation()

所有端点都可以查询基本元数据。此方法返回资源可用的操作规范（创建、更新、删除等）。有关更多信息，我们建议查看Autotask文档。

getEntityUserDefinedFields()

所有端点都可以查询基本元数据。如果资源支持用户定义字段，此方法将返回资源拥有的用户定义字段及其数据类型。有关更多信息，我们建议查看Autotask文档。

query()

可以查询的端点具有一个query()方法。这返回一个具有多个选项的查询构建器。其使用方法和示例如下。

where()

此方法向查询添加一个where过滤器。您可以传递一个比较或一个回调以创建子查询。可以链式多个where语句。例如

<?php

// Basic Comparison
$client->contacts()->query()->where('firstName', 'eq', 'Foo');

// Make sure the field exists
$client->contacts()->query()->where('emailAddress', 'exist'); // OR notexist

// Make a sub-query (these are grouped with the AND conjunction by default)
// This query means: firstName equals Foo AND emailAddress exists
$client->contacts()->query()->where(function ($q) {
    return $q->where('firstName', 'eq', 'Foo')
             ->where('emailAddress', 'exist');
});

以下是where()方法的完整选项

where($field, $operator = null, $value = null, $udf = false, $conjuction = 'AND')

orWhere()

此方法类似于上面的where()方法，但使用OR连接词。示例如下。

<?php

// Make a sub-query (these are grouped with the OR conjunction by default)
// This query means: firstName equals Foo OR emailAddress exists
$client->contacts()->query()->orWhere(function ($q) {
    return $q->where('firstName', 'eq', 'Foo')
             ->where('emailAddress', 'exist');
});

以下是orWhere()方法的完整选项

orWhere($field, $operator = null, $value = null, $udf = false)

此方法返回以下调用

$this->where($field, $operator, $value, $udf, 'OR');

records( int $records )

此方法限制Autotask返回的记录数。传入的整数必须在1到500之间。示例如下。

<?php

$client->contacts()->query()->records(20);

count()

定义完所有过滤器后，您可以运行此方法来查看请求将返回多少条记录。这可能有助于规划分页等。示例如下。

<?php

// This returns an integer specifying how many records will be returned
$result = $client->contacts()->query()->where('firstName', 'contains', 'Foo')->count();

if ($result > 0) {
    echo 'Records exist!';
}

get()

定义完所有过滤器后，您可以运行此方法来对Autotask API发出请求，并返回包含结果的项集合。示例如下。

<?php

$result = $client->contacts()->query()->where('firstName', 'contains', 'Foo')->get();

foreach ($result as $contact) {
    echo $contact->firstName . PHP_EOL;
}

paginate()

get()方法很棒，但如果我有超过500个结果怎么办？如果我想分页结果怎么办？我们为您解决了这个问题！使用paginate()方法返回一个带有辅助属性和方法的Paginator对象。以下将进行解释。

collection

使用分页对象时，您可以使用此属性引用集合。

hasNextPage()

如果存在下一页，则返回true。如果不存在，则返回false。

hasPrevPage()

如果存在上一页，则返回true。如果不存在，则返回false。

nextPage()

尝试检索下一页并返回它。

prevPage()

尝试检索上一页并返回它。

让我们看看这些辅助方法在实际操作中的例子。

<?php

// Let's get the first page
$page = $client->contacts()->query()->where('firstName', 'exist')->paginate();

// We are going to do this until we run out of pages
while(true) {
    // For every contact, print their name and a new line
    foreach ($page->collection as $contact) {
        echo $contact->firstName . PHP_EOL;
    }

    // If a next page doesn't exist, stop the loop
    if(! $page->hasNextPage() ) {
        break;
    }

    // Otherwise retrieve the next page and do it again!
    $page = $page->nextPage();
}

loop()

您可以通过paginate()方法迭代Autotask中的所有记录，也可以使用循环方法轻松完成此操作。此方法接受一个回调函数，该函数将为满足条件的Autotask中的每条记录执行。

注意：这里迭代的记录可能超过500条，这是Autotask的返回限制。只需注意节流。

示例

use Anteris\Autotask\API\Contacts\ContactEntity;

$query = $client->contacts()->query()->where('id', 'exist');

// Get all the contacts from Autotask and echo their name
$query->loop(function (ContactEntity $contact) {

    echo $contact->firstName . PHP_EOL;

});

update($resource)

允许更新项的端点具有一个update()方法。它接受一个实体。下面是使用示例。

注意：目前，更新方法使用PUT请求执行更新。因此，您可能需要检索记录，然后进行更改并提交（如下所示）。我们正在为未来版本开发PATCH替代方案。

<?php

$contact = $client->contacts()->findById(1);

$contact->firstName = 'Something';
$contact->lastName  = 'Different';

$client->contacts()->update( $contact );

anteris-dev / autotask-client

维护者

详细信息