7digital-api 中文文档教程

Question

Node.js API Client

当前头部构建状态：

About 7digital

7digital.com 是一家在线音乐商店在超过 16 个国家和地区开展业务 提供超过 1100 万种高质量的无 DRM MP3 (320kbps) 来自所有 主要标签和范围广泛的独立标签和分销商。 7数码 API 将使您能够访问包括高质量专辑在内的完整目录 艺术，所有曲目的 30 年代预览剪辑，销售佣金，集成 购买和全长流媒体。 更多详细信息，请访问 developer.7digital.net

What is this?

7digital API 的服务器端 javascript 客户端。 最新版本的完整代码文档可以在此处找到。

要使用此库的方法映射文档端点，最好查看 在 API 定义文件。

Installation

通过 npm 安装它

npm install --save 7digital-api

Usage

请参阅示例文件夹以获取有关如何使用它的示例。 如果你已经包括 7digital-api 在你的 package.json 文件中的依赖项中，你可以使用 像这样：

var api = require('7digital-api'),
    artists = new api.Artists();

artists.getReleases({ artistid: 1 }, function(err, data) {
    console.dir(data);
});

要提供您的 OAuth 凭据或如果您想要 XML 响应，您可以使用 配置功能。 以下是您可以这样做的方法：

var api, artists;

api = require('7digital-api').configure({
    format: 'XML',
    consumerkey: 'MY_KEY_HERE',
    consumersecret: 'MY_SECRET_HERE',
    defaultParams: { country: 'fr' }
});

artists = new api.Artists();

artists.getReleases({ artistid: 1 }, function(err, data) {
    console.dir(data);
});

您还可以在每个资源的基础上指定默认参数：

var api, artists;

api = require('7digital-api').configure({
    defaultParams: {
        country: 'fr'
    }
});

artists = new api.Artists({ defaultParams: { pageSize: 15 } });

artists.getReleases({ artistid: 1 }, function(err, data) {
    // 15 releases in france
    console.dir(data);
});

有关完整详细信息，请参阅 developer.7digital.net API 端点及其接受的参数。

OAuth protected endpoints

注意：oauth 访问方法在 0.19.0 中发生了很大变化，更新为 强烈推荐最新版本

Accessing the media delivery api

媒体传输端点的行为与其他端点不同，因为 他们将字节返回给您内容。 您必须签署所有请求，例如 所以：

var api = require('7digital-api').configure({
    consumerkey: 'YOUR_KEY_HERE',
    consumersecret: 'YOUR_SECRET_HERE',
    defaultParams: {
        country: 'es'
    }
});

var oauth = new api.OAuth();
var previewUrl = oauth.sign('http://previews.7digital.com/clip/12345');

// For access to locker / subscription streaming without managed users you
// will need to provide the accesstoken and secret for the user
var signedUrl = oauth.sign('https://stream.svc.7digital.net/stream/locker', {
    trackId: 1234,
    formatId: 26,
    accesstoken: 'ACCESS_TOKEN',
    accesssecret: 'ACCESS_SECRET'
});
// Requesting this URL will now respond with the media data (or redirect to
// an error).

Making requests on behalf of a user to OAuth protected endpoints

注意：oauth 访问方法在 0.19.0 中发生了很大变化

本示例假设您可以访问 oauth/requestToken/authorise 端点来验证用户。 如果您没有此访​​问权限，您将 需要将用户发送到 getRequestToken 提供的 authoriseUrl 并在您的 callbackUrl 被点击时完成身份验证流程。

var api = require('7digital-api').configure({
    consumerkey: 'YOUR_KEY_HERE',
    consumersecret: 'YOUR_SECRET_HERE',
    defaultParams: {
        country: 'fr'
    }
});

var oauth = new api.OAuth();
oauth.getRequestToken('http://callbackurl.com/', authoriseToken);
function authoriseToken(err, requesttoken, requestsecret) {
    oauth.authoriseRequestToken({
        username: 'joe@bloggs.com',
        password: 'top-secret',
        token: requesttoken
    }, function (err) {
        oauth.getAccessToken({
            requesttoken: requesttoken,
            requestsecret: requestsecret
        }, function (err, accesstoken, accesssecret) {
            // use the token and secret to call secure endpoints.
            var apiForJoeBloggs = api.reconfigure({
                defaultParams: {
                    accesstoken: accesstoken,
                    accesssecret: accesssecret
                }
            });
            var user = new apiForJoeBloggs.User();
            user.getLocker({
                pageSize: 1
            }, function (err, response) {
                // Do something with the locker
            });
        });
    });

有关示例，请参阅示例文件夹中的 oauth.js 和 create-user.js 用于获取授权访问令牌和机密的 OAuth 流程 需要代表用户访问任何受保护的端点。

Partner users (3rd party user management)

如果您的密钥有权创建第 3 方（合作伙伴）用户，您必须 配置客户端以允许您使用您的访问受保护的点 用户 ID 而不是访问令牌。 这可以像这样完成：

var api = require('7digital-api').configure({
    consumerkey: 'YOUR_KEY_HERE',
    consumersecret: 'YOUR_SECRET_HERE',
    userManagement: true,
    defaultParams: {
        country: 'fr'
    }
});

// You can now access user endpoints for your users without an access token or
// secret and with your external user id instead
api.User().create({
    userId: 'external-user-12345',
    emailAddress: 'joe@bloggs.com'
    }, function (err, userResponse) {
        api.User().getLocker({
            userId: 'external-user-12345',
            pageSize: 1
        }, function (err, response) {
        // Do something with the user's (empty!) locker
    });
});

Using the environment to configure the client

客户端将检查环境中的以下变量，这使得 可以将您的密钥和秘密保密：

• _7D_API_CLIENT_CONSUMER_KEY - defaults to 'YOURKEYHERE'
• _7D_API_CLIENT_CONSUMER_SECRET - defaults to 'YOURSECRETHERE'
• _7D_API_CLIENT_USER_TOKEN - is not set by default
• _7D_API_CLIENT_USER_SECRET - is not set by default

客户端将检查环境中的以下变量，这使得 更容易控制每个环境的行为（例如在测试中） 必须在您的应用程序代码中分支：

• _7D_API_CLIENT_HOST - defaults to 'api.7digital.com'
• _7D_API_CLIENT_SSL_HOST - defaults to 'api.7digital.com'
• _7D_API_CLIENT_PORT - defaults to 80
• _7D_API_CLIENT_PREFIX - defaults to '1.2'

请注意，这些变量具有最低的优先级（除了默认值）。 IE 在应用程序代码中覆盖它们将优先。

Running the tests

运行单元测试：

npm test

还有集成测试。 测试各种错误处理场景 针对存根 7d api 运行。 可以安装 with：

npm install git://github.com/7digital/api-stub.git

一些集成测试（围绕客户端对 OAuth 的处理）运行 针对真正的 7d api。 为了使这些测试起作用，您需要设置 上面概述的环境变量。 以及以下内容：

• _7D_API_CLIENT_TEST_VOUCHER_CODE

可应用于包含以下项目的购物篮的代金券代码 1p，用于两条腿的 OAuth 测试。

然后可以运行测试：

npm run integration-test