README

NetGalley 公共 REST API 为 NetGalley 的合作伙伴提供了一种与系统交互的方式。该库目前仅支持 PHP，但任何系统都可以通过 REST 访问该 API。

安装

使用 Composer 安装，请在您的 composer.json 文件中添加以下内容

    "require": {
        ...
        "fbng/netgalley-api-client": "*",
        ...
    },

然后运行 composer update，您应该就绪了。

不使用 Composer 安装，请下载最新存档，将其解压到您的项目中，并在代码中添加适当的 require_once 行

require_once('/path/to/lib/NetGalley/API/Client.php');

如果您使用 OAuth2 连接到 NetGalley API（更多信息见下文），也请添加 require_once 行

require_once('/path/to/lib/NetGalley/API/OauthClient.php');

用法

要使用客户端库，首先从 NetGalley 获取一组 API 凭据（如有任何疑问，请联系您的礼宾代表）。这些凭据将是一对密钥/密钥或 OAuth 客户端 ID/密钥，这将确定您将使用哪种方法来访问 NetGalley API。

密钥/密钥连接方法

如果您已收到密钥/密钥凭据，请使用以下示例代码作为访问 API 的基础

use NetGalley\API\Client;

// obtain your credentials from NetGalley
$myUser = 'example';
$myApiKey = 'KEY';
$myApiSecret = 'SECRET';

// if set to true, the client will target a staging server
$testMode = true;

// instantiate the client using your credentials
$client = new Client($myUser, $myApiKey, $myApiSecret, $testMode);

// make an API request; see the relevant documentation
// for details of the API you are requesting; here we
// are creating a new widget for a customer
$response = $client->makeRequest('/private/widgets', 'POST', array(
    'email' => 'customer@gmail.com',
    'isbn' => '1234567890123',
    'market' => 'US',
    'temporaryDrm' => false,
    'firstName' => 'Some',
    'lastName' => 'Customer'
));

// the response will be a JSON-encoded string, so decode it
$response = json_decode($response, true);

// do something with the response
echo 'Response was: ' . print_r($response, true) . PHP_EOL;

OAuth2 客户端 ID/密钥连接方法

如果您已收到 OAuth2 凭据，请使用以下示例代码作为访问 API 的基础

use NetGalley\API\OauthClient;

// obtain your credentials from NetGalley
$clientId = 'CLIENTID';
$clientSecret = 'SECRET';

// if requesting a token to grant third-party access, set the authorization
// code captured by the redirect URI
//
// NOTE: the NetGalley API does not currently support authorizing third-party
// access - this is included only to avoid conflicts in client implementations
// in the future if it ever becomes a supported feature
$authorizationCode = '';

// if set to true, the client will target a staging server
$testMode = true;

// instantiate the client using your credentials
$client = new OauthClient($clientId, $clientSecret, $authorizationCode, $testMode);

// request an access token once (will be set internally for subsequent requests)
$client->requestToken();

// make requests and handle responses the same as above
$response = null;

处理大量数据结果

如果您有权访问任何报告 API，您可能预见到应用程序中的某些实例，其中可能从 API 来大量数据。您可以通过将结果直接流式传输到临时文件来避免将整个数据集加载到内存中。

以下示例中，$responseFile 是一个文件句柄资源，指向包含 API 请求响应数据的临时文件。然后您可以将文件内容写入输出缓冲区以提供 CSV 下载，例如，或将文件重命名为永久位置。

$responseFile = $client->makeFileRequest('/private/reports/example_report', 'GET', array('filter' => 'example'));

if ($responseFile !== false) {

    // Do something with $responseFile

    fclose($responseFile);
}

API 文档

有关每个 REST API 的最新信息，请参阅此存储库中的API 文档。