CoreHound 0.3.1

CoreHound 0.3.1

×

测试已测试✓
Lang语言 Obj-CObjective C
许可证 自定义
发布上次发布2016年9月

由Dustin Bachrach维护。

 
依赖项
AFNetworking~> 2.6
AtSugar~> 0.1
Avenue~> 0.4
AvenueFetcher~> 0.4
JSONModel~> 1.1.2
PromiseKit/CorePromise~> 3.0
UICKeyChainStore~> 2.0
 

CoreHound 0.3.1

CoreHound：开始使用

什么是 CoreHound？

CoreHound 是通过 MediaHound API 访问娱乐图谱的 iOS SDK。跨电影、图书、游戏、电视等媒体内容搜索。通过特性和贡献者发现媒体之间的联系。CoreHound 是一个快速且易于使用的 SDK，让您通过访问整个娱乐内容世界来增强您的 iOS 应用。

安装 CoreHound

要开始使用 CoreHound，请使用 CocoaPods 安装。在您的 Podfile 中添加以下行：

pod 'CoreHound'

运行 pod install，您现在可以通过导入它来使用 CoreHound

#import <CoreHound/MHApi.h>

示例项目

如果您想探索示例项目 SearchLite，只需运行：

pod try CoreHound

SearchLite 项目演示了应用 OAuth、搜索、图像和贡献者关系等许多功能。

链接

链接 描述
SDK 文档 CoreHound 参考文档
MediaHound.com MediaHound 的主页。
@MediaHound 在 Twitter 上关注 MediaHound。
博客 MediaHound 的博客。
娱乐图谱 开发者门户
变更日志 查看每个 CoreHound 版本引入的更改。

媒体内容世界

娱乐图谱包含许多类型的对象——电影、图书、人、特质等。

娱乐图谱包含一系列代表媒体内容、用户、集合等的对象，以及这些对象之间的连接。这些对象和连接构成媒体内容图。社交互动则存在于内容图之上。

娱乐图谱中的每个对象都由一个标识符唯一识别——它的 mhid。例如，电影《拯救大兵瑞恩》有一个 mhid 为 mhmovt8xqWDBFoCiL92HnfA4uYDV8HzPaig8ucgxJEsP。

娱乐图谱中的每个对象都有一类，比如电影、书籍、贡献者等。存在一个定义良好的类型层次结构，这使得您可以轻松地处理不同类型的对象。

拯救大兵瑞恩 是一个 MHMovie，而 第二十二条军规 是一个 MHBook。这两个 MHMovie 和 MHBook 都是继承自 MHMedia 的。这使得我们可以轻松地处理不同内容类型。我们可以将内容视为一个 MHMedia。当我们需要特别处理书籍时，我们可以将它们视为一个 MHBook。

娱乐图谱中的所有对象都继承自 MHObject 类。这个类提供了一个所有图形对象都必须遵循的基本功能。所有对象都有以 MHMetadata 表示的元数据。

属性 描述
mhid 对象的全球唯一标识符
altId 对象的一个类似slug的全球唯一替代标识符
name 对象的可显示给用户的名称
objectDescription 对象的可显示给用户的描述
createdDate 对象在图谱中的创建时间

一些内容类型有更多的元数据属性。例如，所有 MHMedia 对象都有一个扩展 MHMetadata 并新增 releaseDate 属性的 MHMediaMetadata。

大多数 MHObjects 还有一个主图像。主图像是对象的主要视觉表示。一个 MHImage 提供图像元数据，包括不同分辨率的图像的URL。

MHObjects 与其他 MHObjects 有关系。例如，给定一个 MHMovie，我们可以查询对该电影（演员、导演、作曲家等）有贡献的人，如下所示

[movie fetchContributors];

这将为您提供一个与该电影相关的 MHContributors 数组。

娱乐图谱的连通性非常高。以下是一些内容之间连接类型的小示例

要查看类型的完整列表，请访问 图对象。

CoreHound 高度 异步

您与 CoreHound SDK 的几乎所有交互都是通过异步API实现的。CoreHound 使用 promises 作为其异步模式。作为一个简单的例子，要查找《非常嫌疑犯》的发行日期，您会编写

NSString* theUsualSuspectsMhid = @"mhmovI8Y9tWpUFibqYGZYddt1I5q3znlRAuSQ2a6N437";
[MHObject fetchByMhid:theUsualSuspectsMhid].then(^(MHObject* result) {
    NSDate* releaseDate = result.metadata.releaseDate;
    NSLog(@"The Usual Suspects (%@)", releaseDate);
});

要了解更多关于如何与 promises 交互的信息，请参阅PromiseKit 文档。

对象是逐步加载的

由于娱乐图谱包含每个对象及其所有关系的大量信息，因此您必须始终明确获取您想要的数据。

如果您想加载电影的主图像，您必须这样做

[movie fetchPrimaryImage].then(^(MHImage* primaryImage) {
    NSString* url = primaryImage.large.url;
    // Download image at `url`.
});

CoreHound 尽最大努力确保这些获取快速。通常所有数据都会被缓存，因此这些请求将（几乎是）即时完成。只有绝对需要时，CoreHound 才会发出网络请求以获取数据。

有时我们希望在 MHObject 的属性更改时收到通知。所有 MHObject 属性都符合 KVO 标准

注意： CoreHound 对 KVO 通知没有线程亲和性。这意味着所有 KVO 通知都将从后台线程发布。如果您需要在 UI 更新时将 KVO 通知与线程关联起来，请在改变通知发生时确保将它们调度到主线程。

CoreHound 为大数据集而构建

由于娱乐图谱中对象之间存在很多连接，因此所有返回其他 MHObjects 的方法都利用了分页。这意味着您将只得到结果的一个子集。如果需要更多，您可以分批次（一次一页）获取更多内容。

MHPagedResponse 类封装了一页的结果。您可以使用 content 属性来访问该页的结果。

[movie fetchContributors].then(^(MHPagedResponse* response) {
    NSArray* firstPageResults = response.content;
});

如果您需要访问下一页，只需在分页响应上调用 -fetchNext。

[movie fetchContributors].then(^(MHPagedResponse* firstPage) {
    // Access firstPage.content
    return [response fetchNext];
}).then(^(MHPagedResponse* secondPage) {
     // Access secondPage.content
});

搜索娱乐图谱

要执行针对娱乐图谱的搜索，请使用 MHSearch 类。

[MHSearch fetchResultsForSearchTerm:@"The Usual Suspects"
scope:MHSearchScopeMovie].then(^(MHPagedResponse* response) {
    MHObject* firstResult = response.content.firstObject;
    NSLog(@"Found %@", firstResult.metadata.name);
});

搜索结果是标准的 MHObjects，因此您可以像处理从 fetchContributors 获取的 MHObject 一样与之交互。

探索内容之间的关系

在探索内容之间的联系时，仅仅获取 MHObjects 将会受到限制。我们需要了解两个 MHObjects 之间的关系信息。例如，考虑获取一部电影的贡献者。如果我们只得到 MHContributors，我们就不知道那个人如何参与了这部电影。他们是导演、演员，还是制作了这部电影？

为了捕获这些附加信息，我们使用 MHContext 对象。每个 MHPagedResponse 中的条目都是一个 MHRelationalPair，它结合了 MHObject 和 MHContext。

[movie fetchContributors].then(^(MHPagedResponse* response) {
    NSArray* firstPageResults = response.content;
    for (MHRelationalPair* pair in firstPageResults) {
       MHObject* obj = pair.object;
       MHContext* ctxt = pair.context;
    }
});

代表用户执行操作

娱乐只是娱乐图谱的一部分。用户为该图谱带来了社交互动和知识。CoreHound 允许您代表用户进行身份验证并在媒体、创建集合或其他用户之间进行社交操作。

登录用户

CoreHound 提供两种登录用户的方法：用户 OAuth 和企业 OAuth。大多数应用程序将使用用户 OAuth。企业合作伙伴可以加入企业 OAuth 流程。

使用用户 OAuth 登录

即将推出...

使用企业 OAuth 登录

企业 OAuth 允许您直接使用用户的用户名和密码登录用户。您应该提示用户输入他们的用户名和密码，然后调用 MHLoginSession 上的 -loginWithUsername:password 方法。

[MHLoginSession loginWithUsername:usernameField.text
                         password:passwordField.text].then(^(MHUser* user){
    // User succesfully logged in
}).catch(^(NSError* error) {
    // Show the user an error
});

登录成功后，CoreHound 将将用户的凭据安全地存储到钥匙串中。因此，您不再需要存储用户的凭据。您不应在任何地方存储用户的凭据！

一旦用户成功登录一次，在下次访问您的应用程序时，您应该尝试自动为他们登录。

[MHLoginSession loginUsingSavedCredentials].then(^{
    // User succesfully logged in
}).catch(^(NSError* error) {
    if ([error.domain isEqualToString:MHErrorDomain]) {
        if (error.code == MHLoginSessionNoSavedCredentialsError) {
            // User has no saved credentials
            // in the keychain.
        }
        else if (error.code == MHLoginSessionInvalidCredentialsError) {
            // The stored credentials are no longer valid.
            // The user may have changed them elsewhere.
        }
    } 
});

一旦用户登录，您可以通过 MHLoginSession 访问当前登录的用户。

MHUser* currentUser = [MHLoginSession currentUser];

在企业 OAuth 中创建用户

要创建新用户，请调用 MHUser 的创建方法。在创建承诺解决后，您可以使用 MHLoginSession 登录用户。

[MHUser createWithUsername:usernameField.text
                  password:passwordField.text
                     email:emailField.text
                 firstName:firstNameField.text
                  lastName:lastnameField.text].then(^{
    return [MHLoginSession loginWithUsername:usernameField.text
                                          password:passwordField.text];
    // At this point, you no longer need to store the
    // username or password. You should actively stop
    // storing them, to ensure the user's security.
}).then(^(MHLoginSession* session) {
    // At this point the user is now logged in.
    // You can upload a profile image if you'd like
    return [session.user setProfileImage:userImage];
});

登录/注销通知

CoreHound 发布登录和注销通知，如果您想在解耦的方式中监听这些事件。

// Set up notification observer for login
[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(userDidLogin:)
                                             name:MHLoginSessionUserDidLoginNotification
                                           object:nil];

// Set up notification observer for logout
[[NSNotificationCenter defaultCenter] addObserver:self
                                         selector:@selector(userDidLogout:)
                                             name:MHLoginSessionUserDidLogoutNotification
                                           object:nil];

应用程序 OAuth

如果你的应用程序不需要登录用户，则不需要执行用户 OAuth 或企业 OAuth。相反，你需要执行应用程序 OAuth 来访问 MediaHound API。您必须首先拥有 Client ID 和 Client Secret，您可以从 MediaHound 开发者门户中获取。

[[MHSDK sharedSDK] configureWithClientId:@"YOUR CLIENT ID"
                            clientSecret:@"YOUR CLIENT SECRET"];

此方法返回一个 promise，当 SDK 成功配置后该 promise 会解析。请在该 promise 解析之前不要调用 CoreHound。

CoreHound 提供有意义的建议

从任何媒体内容中，您可以找到其他相关媒体内容。给定一个 MHMedia，直接调用 fetchRelated

[movie fetchRelated].then(^(MHPagedResponse* response) {
    MHMedia* firstRelated = response.content.firstObject;
});

如果您想找到多个 MHMedia 的相关内容，可以使用

MHMovie* savingPrivateRyan = /* */;
MHMovie* theUsualSuspects = /* */;
[MHMedia fetchRelatedTo:@[savingPrivateRyan, theUsualSuspects]];

CoreHound 使用 灵活的网络

CoreHound 广泛使用网络以异步提供您请求的数据和结果。但是，对于高级用例，您需要精细控制 CoreHound 请求的调度与您的网络请求相比如何安排。CoreHound 提供了一个清晰的 API，用于控制缓存、优先级、取消和重新优先级。这种网络基础设施是由 Avenue 提供的，Avenue 是一个通用网络库（基于 AFNetworking），您可以在应用的所有网络请求中使用它。

所有 CoreHound fetch API 都有一个接受 3 个参数的版本

  • 强制：是否在使用可用的情况下使用缓存版本
  • 优先级：如何与其他并发网络请求相比安排此请求
  • 网络令牌：一个令牌，允许取消和优先级更改

在下面的示例中，我们获取电影的合作者，明确忽略缓存。我们还将其优先级设置为 低，这意味着它将仅在所有 高 优先级请求完成后执行。

[movie fetchContributorsForced:YES
                      priority:[AVENetworkPriority
        priorityWithLevel:AVENetworkPriorityLevelLow
                  networkToken:nil].then(^(MHPagedResponse* response) {
    // use the results
}];

在下面的示例中，我们创建了 AVENetworkToken 并将其传递给 -fetchContributorsForced:priority:networkToken 方法。之后，我们在令牌上调用 -cancel，这会将网络请求取消（如果它尚未完成）。

AVENetworkToken* token = [[AVENetworkToken alloc] init];
[movie fetchContributorsForced:YES
                      priority:[AVENetworkPriority
        priorityWithLevel:AVENetworkPriorityLevelLow
                  networkToken:token].then(^(MHPagedResponse* response) {
    // use the results
}];
[token cancel];

许可证

CoreHound 在 Apache License 2.0 下可用。有关更多信息，请参阅 LICENSE 文件。