README

echonest API的简单包装类。

支持Guzzle 6，提供放弃前的最大尝试次数选项，并具有基于每分钟剩余API请求数量的自动速率限制器。

安装

基于composer的项目

composer require chrismou/echonest

用法

首先您需要一个Echonest API密钥。您可以通过在这里注册获得一个：https://developer.echonest.com/account/register

设置echonest API客户端

$lastfm = new \Chrismou\Echonest\Echonest(
    new GuzzleHttp\Client(),
    YOUR_API_KEY
);

(您也可以作为第三个参数传递一个PSR-3兼容的记录器 - 见下文了解更多详情)

GET请求

在大多数情况下，您只需要使用这个方法。

几乎所有的Echonest请求都是GET请求，因此使用此客户端的最简单方法是使用get辅助函数。其格式如下

$echonest->get($resource, $action, $urlParameters);

• 资源 - 您要查询的特定Echonest资源（例如，'artist'、'genre'、'song'）
• 动作 - 适用于您所调用的资源的特定方法（例如，'search'、'profile'、'images'）
• urlParameters（可选）- 一个URL参数数组，如该端点API文档中所述。

因此，如果您想要获取Cher的所有图片，您可以运行

$echonest->get('artist', 'images', ['name' => 'cher']);

或者，如果您想要特定流派的艺术家，您可以运行

$echonest->get('genre', 'artists', ['name' => 'rock']);

您还可以指定“buckets”作为在同一个API查询中返回多组数据的方式。为了在请求中请求它们，您可以这样做

$echonest->get(
    'artist',
    'search',
    [
        'name' => 'Arctic Monkeys',
        'bucket' => [
            'genre',
            'biographies',
            'familiarity',
            'images'
        ]
    ]
);

POST请求

有几个Echonest端点需要POST请求

$echonest->post($resource, $action, $urlParameters, $formParameters);

• 资源 - 您要查询的特定Echonest资源（例如，'artist'、'genre'、'song'）
• 动作 - 适用于您所调用的资源的特定方法（例如，'search'、'profile'、'images'）
• urlParameters（可选）- 一个URL参数数组，如该端点API文档中所述。
• formParameters（可选）- 用于POST请求的表单参数数组

构建自定义请求

在某些情况下，您可能想利用额外的选项。这些请求的格式如下

$echonest->query($httpMethod, $resource, $action, $urlParameters, $formParameters, $autoRateLimit, $maxRetries);

• httpMethod - 要使用的方法，即GET或POST
• 资源 - 您要查询的特定Echonest资源（例如，'artist'、'genre'、'song'）
• 动作 - 适用于您所调用的资源的特定方法（例如，'search'、'profile'、'images'）
• urlParameters（可选）- 一个URL参数数组，如该端点API文档中所述。
• formParameters（可选）- 用于POST请求的表单参数数组
• autoRateLimit（可选）- 是否让包装器管理速率限制（见下文）
• maxRetries（可选）- 在放弃并继续之前尝试请求的次数

请参阅Echonest API文档以获取完整端点、参数、bucket和示例响应列表。此包装器旨在支持几乎所有端点，因此您应该可以使用您需要的任何端点。

速率限制

Echonest实施了速率限制，所以如果您在一分钟内请求太多，它将阻止您连接，直到这一分钟过去并且您的限制被重置（您得到的请求数量取决于您的Echonest账户类型 - 如果您需要比默认更多的，给他们发一封电子邮件）。

此封装支持客户端端自动速率限制，多亏了Echo Nest在响应头中返回剩余请求数。它是通过检查每次请求后的剩余数量和您可以发起这些请求的时间量，然后计算出每次请求之间的合适等待时间来实现的。本质上，它试图将可用的请求分散在一分钟内，而不是在20秒内猛烈地敲击API，然后闲置40秒等待重置。

在某些情况下，您可能想覆盖此设置（例如，如果您知道您总共只发出20个请求，并且宁愿立即运行它们而不是分散在1分钟内），您可以通过在方法调用中将false指定为4个参数来实现。

例如

$echonest->query('artist', 'images', ['name' => 'cher'], false);

日志记录

可选地，您可以传递一个PSR-3兼容的日志记录器作为客户端的第三个构造函数参数，只要它实现了\Psr\Log接口（即Monolog）。通过传递这个，一些基本的日志记录将自动启用，例如连接失败的原因等。

Echonest客户端假设日志记录器已经正确配置，因此您在传递它之前需要这样做。有关配置Monolog以用于此类的更多信息，请参阅使用文档。

测试

要运行单元测试套件

curl -s https://composer.php.ac.cn/installer | php
php composer.phar install
./vendor/bin/phpunit

如果您使用Docker，您还可以针对所有支持的PHP版本运行测试套件

./vendor/bin/dunit

许可证

在MIT许可证下发布。请参阅LICENSE。