README

Zendesk PHP API 客户端库

API 客户端版本

这是我们的 PHP API 客户端第二个版本。旧版本的 API 客户端可以在 v1 分支上找到。

API 版本支持

此客户端仅支持 Zendesk 的 API v2。有关更多信息，请参阅我们的 API 文档。

要求

PHP 7.4+

安装

可以使用 Composer 安装 Zendesk PHP API 客户端。

Composer

要安装，请运行 composer require zendesk/zendesk_api_client_php

从 V1 升级到 V2

如果您正在从客户端的 v1 版本升级，我们编写了一份升级指南，突出显示了一些关键差异。

配置

配置是通过 Zendesk\API\HttpClient 的一个实例完成的。该块是必需的，如果不传递，将抛出错误。

// load Composer
require 'vendor/autoload.php';

use Zendesk\API\HttpClient as ZendeskAPI;

$subdomain = "subdomain";
$username  = "email@example.com"; // replace this with your registered email
$token     = "6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv"; // replace this with your token

$client = new ZendeskAPI($subdomain);
$client->setAuth('basic', ['username' => $username, 'token' => $token]);

用法

基本操作

// Get all tickets
$tickets = $client->tickets()->findAll();
print_r($tickets);

// Get all tickets regarding a specific user.
$tickets = $client->users($requesterId)->tickets()->requested();
print_r($tickets);

// Create a new ticket
$newTicket = $client->tickets()->create([
    'subject'  => 'The quick brown fox jumps over the lazy dog',
    'comment'  => [
        'body' => 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, ' .
                  'sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.'
    ],
    'priority' => 'normal'
]);
print_r($newTicket);

// Update a ticket
$client->tickets()->update(123,[
    'priority' => 'high'
]);

// Delete a ticket
$client->tickets()->delete(123);

// Get all users
$users = $client->users()->findAll();
print_r($users);

附件

$attachment = $client->attachments()->upload([
    'file' => getcwd().'/tests/assets/UK.png',
    'type' => 'image/png',
    'name' => 'UK.png' // Optional parameter, will default to filename.ext
]);

将文件附加到评论中

$ticket = $client->tickets()->create([
    'subject' => 'The quick brown fox jumps over the lazy dog',
    'comment' => [
        'body' => 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, ' .
                  'sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.',
        'uploads'   => [$attachment->upload->token]
    ]
]);

边加载

边加载允许您在单个请求中检索相关记录。有关更多信息，请参阅 [文档](https://developer.zendesk.com/rest_api/docs/core/side_loading)。（https://developer.zendesk.com/rest_api/docs/core/side_loading）。

以下是一个使用客户端进行边加载的示例。

$tickets = $client->tickets()->sideload(['users', 'groups'])->findAll();

分页

例如，findAll() 这样的方法调用 API 而不带任何分页参数。如果端点支持分页，则仅返回第一页。要获取所有资源，您需要多次调用 API。

迭代器（推荐）

使用迭代器封装正确的分页类型，允许您在不考虑分页的情况下，通过多次 API 调用检索所有资源

$iterator = $client->tickets()->iterator();

foreach ($iterator as $ticket) {
    echo($ticket->id . " ");
}

如果您需要特定的排序顺序，请参阅文档中的排序部分（例如票据）。

带参数的迭代器示例

$params = ['my' => 'param1', 'extra' => 'param2'];
$iterator = $client->tickets()->iterator($params);

foreach ($iterator as $ticket) {
    echo($ticket->id . " ");
}

使用以下方式更改页面大小： $params = ['page[size]' => 5];
使用以下方式更改排序： $params = ['sort' => '-updated_at'];
- 请参阅文档的详细信息，包括允许的排序字段
组合所有内容： $params = ['page[size]' => 2, 'sort' => 'updated_at', 'extra' => 'param'];

注意:

请参阅文档，以获取您使用的分页类型中排序的正确参数
辅助方法 iterator_to_array 与此实现不兼容

迭代器 API 调用响应

最新响应在迭代器的 $iterator->latestResponse() 中公开。这可能会在调试时很有用。

自定义迭代器

如果您想使用自定义方法而不是默认的 findAll() 进行迭代器，您可以为您收集创建一个迭代器

$strategy = new CbpStrategy( // Or ObpStrategy or SinglePageStrategy
    "resources_key", // The root key with resources in the response, usually plural and in underscore
    [], // Extra params for your call
);
$iterator = PaginationIterator($client->tickets(), $strategy);
foreach ($ticketsIterator as $ticket) {
    // Use as normal
}

这对于过滤端点（如活动自动化）很有用。然而，在这种情况下，您只需将方法从 findAll() 更改为 findActive()，有一个更好的快捷方式

$iterator = $client->automations()->iterator($params, 'findActive');

这与以下类似：

use Zendesk\API\Traits\Utility\Pagination\PaginationIterator;
use Zendesk\API\Traits\Utility\Pagination\CbpStrategy;
$strategy = new CbpStrategy('automations', $params);
$iterator = new PaginationIterator(
    $client->automations(),
    $strategy,
    'findActive'
);

查看如果您需要更多自定义实现，如何使用分页特性。

捕获API错误

这不会改变太多

try {
    foreach ($iterator as $ticket) {
        // your code
    }
} catch (ApiResponseException $e) {
    $errorMessage = $e->getMessage();
    $errorDetails = $e=>getErrorDetails();
}

如果您需要知道错误发生的位置，可以在代码循环中存储所需的信息。

使用CBP（良好）进行查找所有

如果您仍然想使用findAll()，直到CBP成为默认API响应，您必须通过使用参数page[size]显式请求CBP响应。

// CBP: /path?page[size]=100
$response = $client->tickets()->findAll(['page[size]' => 100]);
process($response->tickets); // Your implementation
do {
    if ($response->meta->has_more) {
        // CBP: /path?page[after]=cursor
        $response = $client->tickets()->findAll(['page[after]' => $response->meta->after_cursor]);
        process($response->tickets);
    }
} while ($response->meta->has_more);

立即处理数据。这优化了内存使用，使实时处理成为可能，并有助于遵守API速率限制，提高效率和用户体验。

使用OBP查找所有（仅在端点不支持CBP时推荐使用）

如果CBP不可用，这是您一次获取一页的方式

$pageSize = 100;
$pageNumber = 1;
do {
    // OBP: /path?per_page=100&page=2
    $response = $client->tickets()->findAll(['per_page' => $pageSize, 'page' => $pageNumber]);
    process($response->tickets); // Your implementation
    $pageNumber++;
} while (count($response->tickets) == $pageSize);

立即处理数据。这优化了内存使用，使实时处理成为可能，并有助于遵守API速率限制，提高效率和用户体验。

重试请求

在您的GuzzleHttp\Client实例的HandlerStack上添加RetryHandler中间件。默认情况下，Zendesk\Api\HttpClient重试

超时请求
那些抛出Psr\Http\Message\RequestInterface\ConnectException:class
和那些抛出被识别为ssl问题的Psr\Http\Message\RequestInterface\RequestException:class。

可用选项

选项作为值数组传递给RetryHandler。

max = 2 重试限制
interval = 300 重试之间的基本延迟（毫秒）
max_interval = 20000 最大延迟值
backoff_factor = 1 退避因子
exceptions = [ConnectException::class] 不检查重试_if的重试异常
retry_if = null 可调用函数，可以决定是否重试请求

贡献

欢迎提交拉取请求，但在发送之前请阅读我们的贡献指南。这将加快流程并确保每个人都遵循社区标准。

调试

REPL

为了帮助贡献者，我们添加了一个REPL工具。它是对psysh和symfony控制台的一个简单封装。在您的终端中运行bin/console <子域名> <电子邮件> <API令牌>。这将在客户端变量上自动创建一个Zendesk\API\HttpClient实例。之后，您将能够输入任何有效的PHP语句。该工具的目标是加快开发人员对代码库进行实验的过程。

打印HTTP客户端API调用

您可以使用以下命令打印关于每个API调用的详细信息：

$client = new ZendeskAPI($subdomain);
$client->log_api_calls = true;

HTTP客户端调试

您可以通过此对象检查请求和响应的信息。

$client->getDebug();

版权和许可

根据Apache License 2.0（“许可”）许可；除非遵守许可，否则不得使用此文件。您可以在以下位置获得许可副本：

https://apache.ac.cn/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则在许可下分发的软件按照“原样”基础分发，不提供任何明示或暗示的保证或条件。有关许可的具体语言管理权限和限制，请参阅许可。

wowmaking / zendesk_api_client_php

维护者

详细信息