使用活动源 REST APIUse the activity feed REST API

重要

Microsoft Graph 中/beta的版本下的 api 可能会发生更改。APIs under the /beta version in Microsoft Graph are subject to change. 在生产应用程序中不支持使用这些 API。Use of these APIs in production applications is not supported.

您可以使用 Microsoft Graph 中的活动源 API, 在设备和平台之间恢复用户的活动。You can use the activity feed API in Microsoft Graph to resume a user's activity across devices and platforms. 活动源 API 请求通过委派权限用户活动权限(可用于个人或工作和学校帐户) 代表用户执行。Activity feed API requests are performed on behalf of a user via delegated permissions and the user activity permission, which can be used with either personal or work and school accounts.

用户活动由活动资源表示, 并在由 "收藏"/"活动" 表示的基于时间的订阅源中进行组织。User activities are represented by the activity resource and are organized in a time-based feed represented by the collection me/activities.

什么使用户成为出色的活动?What makes a great user activity?

用户活动不只是启动应用程序, 它们都是应用程序中的特定内容的深层链接。User activities don’t just launch apps — they are deep links into specific content within your app. 您创建的用户活动不仅可以在您自己的应用程序中使用, 还会显示在 Cortana 和 Windows 时间线中—驱动更多的应用程序 reengagement, 使用户可以更轻松地在多个设备上继续使用您的应用程序。The user activities you create can not only be used in your own app, but will also appear in Cortana and Windows Timeline — driving more app reengagement and making it easier for your users to continue using your app across multiple devices.

什么应该成为活动?What should become an activity?

由于每个应用程序都不同, 因此, 每个应用程序开发人员都可以了解将应用程序中的操作映射到用户活动的最佳方式。Because every app is different, it's up to each app developer to understand the best way to map actions within your application to user activities. 例如, 游戏可能会为每个市场活动创建一个活动, 文档创作应用程序可能会为每个唯一文档创建一个活动, 并且业务线应用程序可能会为每个工作流创建一个活动。For example, games might create an activity for each campaign, document authoring apps might create an activity for each unique document, and line-of-business apps might create an activity for each workflow.

在应用程序中定义 activitites 时, 请遵循以下准则:Apply the following guidlines as you define activitites in your app:

操作 : 记录一组相关用户操作的单个活动。DO: Record a single activity for a group of related user actions. 如果您的应用程序用于一系列相关的内容, 则记录整个参与会话的单个活动可能很有意义。If your application is used for a sequence of related content, it probably makes sense to record a single activity for the entire engagement session.

播放列表方案: 这一点尤其适用于音乐播放列表或电视节目-可以更新单个用户活动以显示进度。Playlist scenarios: This is especially relevant for music playlists or TV shows — a single user activity can be updated to show your progress. 在这种情况下, 您将有一个用户活动, 其中多个历史项目表示一段时间内多天或几周的服务。In this case, you will have a single user activity with multiple history items representing periods of engagement across multiple days or weeks.

操作 : 将用户数据存储到云。DO: Store user data to the cloud. 如果要支持跨设备活动, 则需要确保将 reengage 此活动所需的内容存储到云位置。If you want to support cross-device activities, you need to make sure the content required to reengage this activity is stored to a cloud location. 例如, 如果您在每次用户编辑文档时发布活动, 则应将文档存储在云中, 而不是在用户的设备上本地存储, 以便启用跨设备 reengagement。For example, if you publish an activity each time a user edits a document, the document should be stored in the cloud as opposed to locally on the user's device in order to enable cross-device reengagement.

请勿执行以下操作: 为用户无需在将来恢复的操作创建用户活动。DO NOT: Create a user activity for actions that users do not need to resume in the future. 如果您的应用程序用于完成简单的一次性操作, 这些操作不会保留状态以供将来跟踪, 则您可能不需要编写用户活动。If your application is used to complete simple, one-time operations that do not persist status for you to track in the future, you probably do not need to write a user activity.

若要清楚, 即使用户活动出现在 Windows 日程表中, 也不会将其设计为版本控制工具—选择基于文档的活动应始终显示该文档的最新版本 (包括其他用户所做的更改)。To be clear, even though user activities appear in Windows Timeline, this is not designed as a versioning tool — choosing a document-based activity should always show the latest version of that document (including changes that were made by another user.)

请勿执行以下操作:其他用户完成的操作创建用户活动。DO NOT: Create a user activity for actions completed by other users. 如果某人向用户发送邮件, 或在您的应用程序中 @mentions 用户, 则不应编写新活动。If someone sends the user a message, or @mentions the user within your app, you should not write a new activity. 通过呈现通知, 可以更好地提供这些交互。These interactions are better served by surfacing notifications.

协作方案: 如果有多个用户在同一个活动 (如 Word 文档) 上工作, 则在您最后一次编辑文档后, 其他用户已对其进行了更改。Collaboration scenarios: If multiple people are working on the same activity (such as a Word document), there will be cases when another user has made changes to the document after you last edited it. 在这种情况下, 应用程序开发人员可能需要更新活动中的可视元素, 以反映对文档所做的更改。In this case, app developers might want to update the visual elements in the activity to reflect changes made to the document. 若要执行此操作, 应用程序可能会更新现有活动, 而不会创建新的历史记录项。To do this, the app might update the existing activity without creating a new history item.

注意: 如果要为 web 应用程序发布活动, 请务必同时activationURL fallbackURL为每个活动包含和。Note: If you're publishing activities for a web application, it's important to include both an activationURL and a fallbackURL for each of your activities. 这些活动将从 Microsoft 体验 (如 Windows 日程表) 按预期方式将用户重新启动到应用中。The activities will launch the user back into your app as expected from Microsoft experiences like Windows Timeline.

应用交互模式和用户活动App interaction patterns and user activities

您创建的用户活动将根据您的应用程序的交互模式而变化。The user activities that you create will vary based on the interaction pattern of your app. 虽然每个应用程序不同, 但大多数都属于以下交互模式之一:While every app is different, most will fall into one of the following interaction patterns:

  • 基于文档的应用程序-为每个文档创建一个活动, 其中包含一个或多个历史记录, 并反映使用时间段。Document-based apps — Create one activity per document with one or more history records reflecting periods of use. 对文档进行更改时, 更新活动卡非常重要。It is important to update your activity card as changes are made to the document.
  • Media 回放应用—根据内容 (如播放列表、程序或独立内容) 的逻辑分组创建一个活动。Media playback apps — Create one activity per logical grouping of content such as a playlist, program, or standalone content.
  • 游戏—为每个已保存的游戏或世界创建一个活动。Games — Create one activity for each saved game or world. 如果你的游戏仅支持一系列级别, 则可以在一段时间内编写相同的活动, 尽管你可能需要更新卡片以显示你的最新进度或成就。If your game supports only a single sequence of levels, you can write the same activity over time, although you might want to update your card to show your latest progress or achievements.
  • 实用程序应用程序-如果用户要恢复的应用程序中没有任何内容, 则不应发布活动。Utility apps — If there is nothing within your app that users would want to resume, you should not publish activities. 一个很棒的示例是简单的单一用途应用 (如计算器)。A good example is a simple single-purpose app like calculator.
  • 业务线应用程序—用于管理简单任务或工作流的许多应用程序都存在。Line-of-business apps — Many apps exist for managing simple tasks or workflows. 为通过您的应用程序访问的每个单独的工作流创建一个活动。Create one activity for each separate workflow accessed through your app. 例如, 每个零用金报销单都是一个单独的活动, 因为您可能想要单击该活动以查看该活动是否已获得批准。For example, each expense report would be a separate activity, because you might want to click that activity to see if it was approved.

一些复杂的应用程序包含多个交互模式。您可能需要针对应用程序处理的不同应用场景遵循不同的用户活动创建模式。Some complex apps include multiple interaction patterns. You might want to follow different user activity creation patterns for different scenarios handled by your app.

后续步骤Next steps

是否要查找更多创意?Looking for more ideas?