收藏服务：第二阶段功能规范

Andy Boyd

MSDN Architectural Samples Team

2001 年 9 月

摘要：本文档定义在项目的第二阶段中收藏 Web 服务示例应用程序将实现的功能。在收藏 Web 服务示例的第二阶段中将添加 Passport 身份验证、高级客户端和 ASP.NET 客户端。

MSDN Architectural Samples Team 非常希望您能提供有关本规范的反馈，您可以访问 MSDN Web 服务 newsgroup（英文），并将反馈放在 news:microsoft.public.msdn.webservices 中。

实施概述

本文档定义在项目的第二阶段中收藏 Web 服务将实现的功能。在收藏 Web 服务示例的第二阶段中将把 Passport 身份验证、高级客户端和 ASP.NET 客户端作为附加功能添加进来。第二阶段的目的是简化和扩展服务，并使我们的收藏服务应用程序能够利用未来技术的优势，这其中包括 Microsoft .NET My Services（以前称为 HailStorm）。

注意：本文是收藏服务示例 Web 应用程序第二阶段功能规范的草案。MSDN Architectural Samples Team 之所以提前提供此规范，其目的就是希望得到有关收藏服务的下一版本将要实现的功能的注释、建议和反馈。

除了有关现有项目的注释外，MSDN Architectural Samples Team 还希望得到有关以后示例的问题、一般注释和建议。请通过 MSDN Web 服务 newsgroup（英文）将您的问题和建议提交给我们。

1. 项目概览和范围

1.1 问题陈述

在第一阶段的收藏服务发布后，虚构的 Cold Rooster 咨询公司希望为被授权者和最终用户改善其站点的功能。通过满足更多的 Web 服务需求，Cold Rooster 的目标是吸引更多的被授权者并使最终用户愿意使用其（我们的）服务托管他们的数据。收藏服务将继续完善，努力使潜在的客户信服 Web 服务的品质与实用性。此服务将继续：

提高潜在客户的 Web 站点的价值

展示我们开发与操作实践的品质

以合理的成本实现和部署

第一阶段实现的收藏服务存在几个缺点：

用户数据局限于每个被授权者——即，一个站点的收藏数据无法通过另一个站点访问。

用户需要为使用收藏服务的每个站点创建唯一的登录信息，并且还要记住这些信息。

虽然 Web 服务可同时支持 Web 和高级客户端，但示例收藏服务只建立了 Web 客户端。

1.2 第二阶段修订和更新

在第二阶段中，将在收藏服务中添加以下功能：

用户身份验证将通过 Microsoft Passport Service 2.0 进行处理。这可使用户在访问站点时自动访问收藏数据而不必创建单独的登录帐户。

用户可以通过同一身份访问所有被授权者。通过获得使用此服务授权的任意站点，用户都可以访问同一收藏集（每个帐户）。

收藏服务的功能将添加到 Cold Rooster 服务中心应用程序中。在 ColdStorage Service（英文）方面工作的小组当前正在开发此应用程序。收藏服务在 Web 页或 Microsoft? Windows? 应用程序中都可正常运行。

收藏服务的部分组件将被按照 .NET 标准重新编写，以改善服务的性能和功能。当前，要重新建立的组件包括：

报告 UI

管理 UI

站点 UI

报告和 GetFavorites 数据将以纯 XML（而非 HTML 编码的 XML）格式进行传递。

为示范服务的跨站点功能，将通过附加的单独示例站点扩展 Cold Rooster Web 站点，从而展示唯一用户的概念。通过使用 Microsoft 及可能的非 Microsoft (Linux) 站点，附加的站点还将分别展示收藏服务遵循标准的情况。

1.3 范围

在第二阶段中，Cold Rooster 咨询公司将实现并部署收藏 Web 服务，从而授权 Web 站点开发商在后台使用该服务管理他们客户的收藏。用户可以在任何获得使用该服务授权的 Web 站点保存收藏，并且可以在任何获得使用该服务授权的站点上访问这些收藏。通过最终用户的权限，被授权者可以替用户添加、删除、编辑和组织收藏。被授权者也可以替单个客户检索其存储的所有收藏。收藏 Web 服务还可以生成被授权者每周使用情况以及常用收藏的报告。

除 Web 服务以外，还将实现并部署一些工具以协助服务的操作。这些工具包括管理被授权者的工具、报告生成器以及服务管理工具。Cold Rooster 咨询公司还将为被授权者提供示例和文档，以说明如何将收藏服务集成到 Web 站点或高级客户端中。这些示例由三个示例 Web 站点、一个带有源代码的高级客户端以及一套完整的服务软件开发工具包 (SDK) 组成。

2. 概念模型

此部分描述与收藏服务进行交互的参与者，并定义与理解使用案例和需求相关的主要概念。概念模型的大部分信息与第一阶段是相同的。有关其详细信息，请参阅Phase One Functional Specification（英文）。

2.1 子系统

本文档使用以下术语标识收藏服务中的逻辑子系统和数据存储区。

表 1：收藏服务子系统和数据存储区

名称	说明
收藏服务	整个系统
收藏 Web 服务	此部分系统为客户端应用程序提供用户收藏管理服务。
收藏 Web 站点	收藏服务的可浏览界面，提供有关服务、管理服务以及提供给被授权者的文档的一般信息。对于第二阶段，将包括三个示例 Web 站点以及 Cold Rooster 咨询公司的主站点。
收藏许可证管理系统	由客户帐户代表和服务经营者用来创建和维护许可证的子系统。
收藏被授权者数据存储区	保存有关被授权者信息的数据存储区。在第二阶段中，收藏服务仍将是内部维护的数据库；Passport 2.0 将只用于用户身份验证。
收藏报告服务	此部分系统为客户端应用程序提供有关被授权者使用收藏 Web 服务情况的报告。
收藏统计系统	由管理者以及服务经营者用来查看有关收藏服务使用方面统计信息的子系统。
Web 客户端应用程序	由被授权者提供的 Web 站点，最终用户可使用该站点查看、访问和管理收藏。
Cold Rooster 服务中心	MSDN Architectural Samples ColdStorage 组正在开发的高级客户端，该客户端将被扩展以包含收藏服务功能。

2.2 授权模型

此服务将被授权给希望在其 Web 站点中提供收藏服务功能的公司。此项服务的主要增值点是：它为最终用户提供了以书签形式标记订阅站点内容的能力，并使被授权者可基于内容需要、用户配置文件或内容/产品的推广，为最终用户提供或建议附加的收藏。虽然此服务的主要目的不在于获得收益，但将根据收藏请求的数量以及使用服务合约的时间长度向被授权者收取一定费用。

表 2：收藏服务授权模型

每月收藏请求的数量
合约时间	0-999	1000-9,999	10,000-50,000	50,000+
1 个月	49.95/月	149.95/月	249.95/月	499.95/月
6 个月	44.95/月	139.95/月	229.95/月	459.95/月
12 个月	39.95/月	129.95/月	209.95/月	399.95/月

高级客户端将成为 Cold Rooster 咨询公司站点的服务，同时也是服务的使用者（被授权者）。高级客户端将以广告模式维持其自身的生存，该模式基于 ColdStorage Project（英文）使用的广告服务。高级客户端不包含在服务自身的收益或授权模型中，它和示例 Web 客户端将被作为研究示例提供给被授权者。

此外，被授权者需要支付因使用 Passport 作为其身份验证服务而产生的费用。Passport 本打算对服务经营者按年度象征性地收取许可证使用费用，但目前 Microsoft 正要取消此费用。

3. 使用案例

以下使用案例说明了外部参与者（最终用户和客户端应用程序等）执行一般操作时收藏服务的行为。大部分使用案例与第一阶段使用案例是相同的——因此，这里只介绍第二阶段中新增的使用案例。有关其他使用案例的详细信息，请参阅 Phase One Functional Specification（英文）。

3.1 服务器实用程序使用案例

此部分列出完整使用案例的一部分。

验证许可证

收藏服务验证所提供的被授权者标识符是否对应于使用服务所需的有效许可证。如果不是，则向客户端返回错误信息（客户端错误：无效被授权者）。

有效许可证已被激活，它没有过期，并且没有被挂起。

验证用户 ID

收藏服务验证所提供的 Passport ID (PID)。由于实际用户凭据的验证由 Passport 处理，所以服务将只确认该 PID 是否存在。如果不存在，服务将向客户端返回错误（客户端错误：无 Passport ID）。

记录操作

收藏服务保存一份记录，其中包括调用者的 IP 地址和被授权者 ID、操作开始的日期和时间、操作完成所需时间、操作类型、应答类型（成功、服务器错误、客户端错误），以及执行操作者的 PID。

添加新用户

通过同时指定被授权者标识符和 PID，客户端应用程序向收藏服务提交请求以添加新的用户。

收藏服务验证许可证，然后验证用户 ID。如果许可证和用户 ID 都有效，收藏服务将在数据存储区中创建新的用户记录。如果成功添加记录，将向客户端应用程序返回成功应答。如果用户 ID 已存在于数据存储区中，或由于发生某种内部处理错误使得服务无法创建新的用户记录，则向客户端应用程序返回错误（客户端错误：用户 ID 已存在于数据存储区中；服务器错误：无法存储用户）。检查重复的用户 ID 是否是由于未区分大小写造成的。收藏服务记录添加新用户的操作。

登录到服务

客户端 Web 站点重定向到 Passport 身份验证站点以确认用户是否已被验证。

如果用户已被验证，Passport 重定向回客户端站点（指出该用户已被验证）并传送用户的 PID。

用户身份验证是通过 Passport Manager 对象执行的。有关详细信息，请参阅 http://www.passport.com/DevInfo/dev_signin.asp（英文）。

当最终用户第一次使用 Passport 进行身份验证时，客户端应用程序将通过同时指定被授权者标识符和 PID，向收藏服务提交请求以检索用户的收藏。有关详细信息，请参阅使用案例检索所有收藏。如果 PID 不存在于数据库中，将添加新的用户帐户。

注销服务

客户端 Web 站点从用户的计算机中删除会话 Cookie，然后对自己进行刷新。然后，客户端 Web 站点将检测到用户尚未登录，并显示登录选项。

3.2 收藏服务使用案例

被授权者从 Web 客户端得到的益处在于，用户可以书签形式标记被授权者站点的内容，并且可以在任何地方访问该内容——即，用户可以书签形式标记任何被授权者站点的内容，并且可通过任意一个被授权者站点访问它们。在 Web 客户端中只包含快捷添加收藏的功能；但有偿使用服务后，一个最大的好处就是可鼓励用户访问被授权者的 Web 站点。

检索所有收藏

如果用户尚未登录到 Passport，则从客户端 Web 站点选择登录选项。如果用户已经登录，客户端 Web 站点通过站点被授权者 ID 和 PID 向收藏服务提交 GetFavorites 请求。服务验证许可证 ID 和 PID。如果两者都有效，服务将以 XML 格式返回用户的所有数据。如果发生某种内部处理错误，使得服务无法检索收藏，则向客户端应用程序返回错误（服务器错误：无法检索收藏）。收藏服务记录该操作。

添加新的收藏

在特定 Web 站点上，如果用户要添加收藏，他们就可以选择“添加新的收藏”链接。此链接将显示在可显示和处理 URL 的任何页上，包括文档和 Internet Explorer 链接栏。选中后，客户端 Web 站点将检查以确认用户是否已登录，然后客户端应用程序通过指定 PID、统一资源定位符 (URI)、类别 ID、该页的助记名称以及被授权者标识符，向收藏服务提交请求以在用户的收藏中添加该页。（客户端应用程序可让用户选择现有类别并输入收藏名称，或只简单指定用户的根类别并将页标题作为助记名称。）

收藏服务验证许可证，然后验证用户 ID。如果许可证和 PID 有效，收藏服务将验证 URI、类别 ID 和助记名称。如果 URI、类别 ID 和助记名称无效，将返回错误。可能的错误包括：

客户端错误：URI 至少要包含一个字符

客户端错误：URI 的语法无效

客户端错误：类别不存在

客户端错误：助记名称至少要包含一个字符

客户端错误：类别中已存在该助记名称

如果所有参数都有效，收藏服务将在数据存储区中创建新的收藏。如果成功添加记录，将向客户端应用程序返回新的收藏 ID。如果发生某种内部处理错误，使得服务无法创建新的用户记录，则向客户端应用程序返回错误（服务器错误：无法存储收藏）。收藏服务记录添加新收藏的操作。

管理收藏

登录后，用户从客户端 Web 站点提供的 Web 控件中选择“管理收藏”选项。客户端 Web 站点将检索所有收藏，然后按类别显示收藏，并在同时显示选项，用于手动添加收藏、添加新的类别、删除收藏、删除类别、重命名收藏、重命名类别、移动收藏和复制收藏。

手动添加收藏

在“管理收藏”屏幕上，用户可以手动添加收藏。非被授权者收藏只能通过选择此选项添加。用户将被提示输入收藏的 URL、助记名称，同时在屏幕上还将显示列表框，以便用户选择类别。根收藏文件夹为默认位置。选中后，客户端 Web 站点将检查以确认用户是否已登录，然后客户端应用程序通过指定 PID、URI、类别 ID、该页的助记名称以及被授权者标识符，向收藏服务提交请求以在用户的收藏中添加该页。收藏服务验证许可证，然后验证用户 ID。如果许可证和 PID 有效，收藏服务将验证 URI、类别 ID 和助记名称。如果 URI、类别 ID 和助记名称无效，将返回错误。可能的错误包括：

客户端错误：URI 至少要包含一个字符

客户端错误：URI 的语法无效

客户端错误：类别不存在

客户端错误：助记名称至少要包含一个字符

客户端错误：类别中已存在该助记名称

如果所有参数都有效，收藏服务将在数据存储区中创建新的收藏。如果成功添加记录，将向客户端应用程序返回新的收藏 ID。如果发生某种内部处理错误，使得服务无法创建新的用户记录，则向客户端应用程序返回错误（服务器错误：无法存储收藏）。收藏服务记录“添加新收藏”操作。

其他功能

有关基本功能（如添加、删除和重命名收藏和类别）的详细信息，请参阅 Phase One Functional Specification（英文）。

3.3 收藏服务高级客户端使用案例

高级客户端除了将作为收藏服务的核心外，还将作为 Cold Rooter 咨询公司的创收工具。高级客户端将成为用户收藏的主要管理工具，而不是自由添加收藏的交互工具（Web 控件就是这种交互工具）。

查看收藏

此项为高级客户端的默认视图。高级客户端将显示两个按类别排列的窗格，一个树形视图和一个叶对象视图。

添加新的收藏

在高级客户端中未启用一次单击即可添加的功能。此功能在 Web 客户端中使用，它将和被授权者进行交互。在高级客户端中可通过单击“添加收藏”按钮，手动添加收藏。

手动添加收藏

此功能与 Web 客户端使用案例中的功能相同。

导入收藏

此功能将使用 IShellUIHelper::ImportExportFavorites 接口把本地存储的所有收藏或书签导入到 Web 服务中。

导出收藏

此功能将把所有收藏服务的收藏和类别导入到 Internet Explorer 的“收藏”菜单中。

同步收藏

同步收藏同时执行导入收藏和导出收藏操作。

添加新的类别

功能上与 Web 客户端使用案例相同，高级客户端将通过上下文菜单、Windows 菜单和工具栏选项启用“添加类别”功能。

删除收藏

功能上与 Web 客户端使用案例相同，高级客户端将通过上下文菜单、Windows 菜单和工具栏选项启用“删除收藏”功能。

删除类别

功能上与 Web 客户端使用案例相同，高级客户端将通过上下文菜单、Windows 菜单和工具栏选项启用“删除类别”功能。

重命名收藏

功能上与 Web 客户端使用案例相同，高级客户端将通过上下文菜单、Windows 菜单和高级客户端单击并输入方法启用“重命名收藏”功能。

重命名类别

功能上与 Web 客户端使用案例相同，高级客户端将通过上下文菜单、Windows 菜单和高级客户端单击并输入方法启用“重命名类别”功能。

移动收藏

功能上与 Web 客户端使用案例相同，高级客户端将通过上下文菜单、Windows 菜单和高级客户端拖放方法启用“移动收藏”功能。拖放时，移动收藏将作为默认操作。当使用鼠标右键单击收藏时，上下文菜单中将显示“移动收藏”选项；当使用鼠标右键单击收藏并将其拖动到新的类别时，上下文菜单中将显示“移动收藏”和“复制收藏”选项。

复制收藏

功能上与 Web 客户端使用案例相同，高级客户端将通过上下文菜单、Windows 菜单和高级客户端拖放方法启用“复制收藏”功能。拖放时，移动收藏将作为默认操作。当使用鼠标右键单击收藏时，上下文菜单中将显示“复制收藏”选项；当使用鼠标右键单击收藏并将其拖动到新的类别时，上下文菜单中将显示“移动收藏”和“复制收藏”选项。

3.4 授权使用案例

除了将接口更新为 ASP.NET 以外，收藏服务的注册过程没有变化。有关完整的授权服务的详细信息，请参阅 Phase One Functional Specification（英文）。

3.5 报告使用案例

有关报告服务方面的唯一更改是服务将传递纯 XML，而非 HTML 编码的 XML。此更改不会反映在任何使用案例中。有关完整的报告的详细信息，请参阅 Phase One Functional Specification（英文）。

4. 交付内容

此部分列出收藏服务第二阶段将交付的软件和文档。

4.1 Web 服务

将在 Internet 上部署以下 Web 服务：

收藏登录服务处理被授权者的身份验证/授权。被授权者登录服务仍将使用内部数据库，而非 Passport。

收藏 Web 服务处理用户收藏管理。服务的用户接口元素将使用 .NET 框架编写。

收藏报告服务生成使用收藏服务情况的报告。

4.2 开发工具包

开发工具包将包含：

文档，其中包括：

参考页，描述所有 Web 服务提供的每个操作。

开发人员指南，解释如何通过客户端应用程序使用 Web 服务。

测试指南，解释如何在客户端应用程序中测试 Web 服务的使用情况。

有关访问测试服务的指导以及测试服务限制的说明。

已知问题的列表，包括特定工具集的互用问题。

针对操作人员的疑难解答过程。

有关所提供的客户支持的信息。

示例客户端应用程序：

两个使用收藏 Web 服务的 Web 客户端应用程序。其中至少有一个服务用于非 Microsoft 的 Web 服务器，如 Apache。此示例用于展示基于标准的 XML Web 服务在不同平台上的使用。

使用收藏 Web 服务的 Windows 高级客户端应用程序。ColdStorage 项目组正在开发的 Cold Rooster 服务中心将作为高级客户端，并且其中将附带实现收藏服务功能的附加页。

4.3 收藏 Web 站点

收藏 Web 站点为收藏服务提供 Cold Rooster 咨询公司示例用户接口。除 Phase One Functional Specification（英文）中的功能外，还有两个用于第二阶段的附加示例站点（总共三个站点）。这三个示例站点都可以独立的被授权者身份使用独立的域名来访问收藏服务。收藏服务功能将通过每个站点的 Passport 2.0 启用，展示了查看收藏数据只与用户有关而与所访问的被授权者站点无关这一功能。

4.4 收藏 Windows 客户端

收藏 Windows 客户端将作为 Cold Rooster 服务中心附加的选项卡，通过它可以在 Windows 控件中访问收藏服务的所有用户功能。高级客户端将仅用于收藏管理工具，因此不会提供添加其他收藏的便捷方法，无论这些收藏来自于被授权者还是非被授权者站点。这样对功能进行限制是为了促使用户使用被授权者 Web 站点添加收藏，从而使付费的被授权者得到更多的实惠。高级客户端拥有以下主要功能：

用于复制和移动收藏和类别的高级客户端拖放功能

所有主要收藏服务管理任务的上下文菜单

所有主要收藏服务管理任务的工具栏按钮

所有收藏服务管理任务的 Windows 菜单选项

从浏览器导入、导出到浏览器以及同步收藏的按钮

4.5 Internet 应用程序

以下应用程序将部署在 Cold Rooster 咨询公司的内部：

收藏许可证管理系统

收藏统计系统

5. 要求

此部分总结并按优先级列出收藏服务第二阶段所要满足的要求。

每个要求都被指定一个优先级。优先级编号范围为 1 到 3：

没有它将无法运行

应该具有

最好具有

要求部分只显示第二阶段中独有的功能或开发要求。有关基本的服务要求，请参阅 Phase One Functional Specification（英文）。

5.1 第二阶段服务要求

用户收藏管理

要求	优先级	标题	注释
2-101	2	收藏 Web 客户端检测 Passport 登录并自动启用收藏服务。	无
2-102	2	收藏高级客户端检测 Passport 登录并自动启用收藏服务。	无
2-103	1	在 Cold Rooster 咨询公司和示例站点的所有页中显示“登录到 Passport”框。	无
2-104	1	在高级客户端中提供“登录到 Passport”功能。	无
2-105	1	用户通过使用同一 Passport 帐户，可以从所有预订服务的站点中查看收藏。请参阅 2-603。	无

安全性

要求	优先级	标题	注释
2-201	1	审核踪迹	对于每个服务请求，存储调用者的 IP 地址、站点 ID、Passport 用户 ID (PUID)、日期/时间戳、请求类型和应答类型。

非功能性要求

要求	优先级	标题	注释
2-401	1	所有主要服务组件都使用 .NET 框架编写。	无
2-402	1	GetFavorites 数据以纯 XML 格式传递。	无

报告

要求	优先级	标题	注释
2-501	1	报告服务数据以纯 XML 格式传递。	无

开发人员文档和工具

要求	优先级	标题	注释
2-601	2	Passport 的开发人员文档	解释此流程：注册并使用 Passport 对用户进行身份验证，然后将该身份验证传递给 Web 服务。
2-602	1	服务开发人员文档	解释如何将 .NET 功能集成到 Web 服务和服务客户端中。
2-603	1	示例 Web 站点	向 Web 站点开发人员展示如何将收藏服务集成到他们的客户端应用程序中。将提供三个 Web 站点作为示例，以展示唯一用户登录功能。部分示例站点将基于非 Microsoft 平台，以示范 Web 服务遵循工业标准的情况。
2-604	2	示例高级客户端	向被授权者展示如何添加集成了收藏服务的高级客户端功能。

高级客户端功能

要求	优先级	标题	注释
2-901	1	菜单栏	用于访问所有功能的标准 Windows 菜单栏。
2-902	1	鼠标右键单击显示的上下文菜单	用鼠标右键单击浏览器（默认为根类别）中的类别或空白区域应该显示选项：（手动）添加收藏、添加类别、删除收藏、复制收藏、移动收藏、重命名收藏。
2-903	2	工具栏	应为主要功能启用工具栏按钮，包括：（手动）添加收藏、添加类别、删除（收藏或类别）、复制收藏、移动收藏、重命名收藏。
2-904	1	拖放	收藏和类别可被拖放到任何新的收藏或类别中。
2-905	3	拖放上下文菜单	用鼠标右键单击并拖动，应该显示上下文菜单，以复制收藏或移动收藏（默认为移动）。
2-906	3	从浏览器导入收藏	只需进行一次单击操作，客户端就可实现以下功能：从浏览器导入所有用户收藏、比较服务中现有的收藏并向列表中添加新的收藏。
2-907	3	将收藏导出到浏览器	只需进行一次单击操作，客户端就可实现以下功能：导出服务中的所有收藏、比较浏览器中现有的收藏并向浏览器收藏列表中写入新的条目。
2-908	3	同步收藏	同时执行从浏览器导入和导出收藏的操作。
2-909	1	广告服务	在 .NET 存储项目中使用的广告服务控件将显示在收藏服务客户端的页面中。此功能体现客户端的收入模型。
2-909	2	更改视图控件	下拉列表框显示收藏的预配置视图。视图显示取决于随收藏收集的元数据和由服务提供的元数据。视图包括： 显示 Cold Rooster 收藏。 显示 Cold Rooster 收藏和其他收藏。 按被授权者排列所有收藏。