使用项目计划 API 执行操作

30 分钟

项目计划 API 为您提供对计划实体执行创建、更新和删除操作的能力。可使用通用 API 引入客户的项目管理工具并将其集成到 Project Operations 中，在客户首选的项目管理工具中完成任务计划。您可以通过 Project for the Web 中的计划引擎管理这些实体。计划 API 支持以下实体。

实体名称	实体逻辑名称
项目	msdyn_project
项目任务	msdyn_projecttask
项目任务依赖关系	msdyn_projecttaskdependency
资源分配	msdyn_resourceassignment
项目存储桶	msdyn_projectbucket
项目团队成员	msdyn_projectteam
项目检查清单	msdyn_projectchecklist
项目任务与标签关系	msdyn_projecttasktolabel

通过组织从旧系统迁移到 Project Operations 的数据迁移应用场景，了解 API 的使用。该应用场景接近实际应用场景，有助于展示计划 API 的使用。以下实体关系图显示旧应用程序使用的数据模型。

数据模型中涉及的表如下：

帐户——保留组织的所有帐户。可为帐户运行若干可用项目。
项目——保留帐户的项目特定信息。
任务——保留与交付项目关联的任务。
任务依赖项——保留项目中各种任务之间的相互依赖关系。任务可能依赖其他任务；基本上，必须先完成前置任务，然后才能开始当前任务。
资源——保留有关组织拥有的各种资源的信息。资源也可以是资产。为了简单起见，假定资源是员工。
项目团队——保留项目与资源之间的关系。资源可负责多个项目，项目将拥有多个资源。在这种情况下，项目团队表示用于建模多对多关系的桥接表。
分配——保留关联资源与任务的信息。这也是表示多对多关系的桥接表。

数据迁移示例

本练习旨在演示 API 的使用，因此将跳过有关从源系统拉取数据的部分。在本练习范围内，您将硬编码源数据并处理有限数量的记录。以下图表展示作为练习一部分的数据。本练习涉及两个帐户和三个相关项目以及一些任务和资源。示例数据足以演示大部分 API 功能，例如任务依赖项、任务分组等。

使用计划 API 进行数据迁移

当前项目计划 API 包括：

msdyn_CreateProjectV1——使用此 API 创建项目。立即创建项目和默认项目存储桶。
msdyn_CreateTeamMemberV1——使用此 API 创建项目团队成员。立即创建团队成员记录。
msdyn_CreateOperationSetV1——使用此 API 计划将在事务中执行的若干请求。
msdyn_PSSCreateV1——使用此 API 创建实体。实体可以是支持创建操作的任意项目计划实体。
msdyn_PSSUpdateV1——使用此 API 更新实体。实体可以是支持更新操作的任意项目计划实体。
msdyn_PSSDeleteV1——使用此 API 删除实体。实体可以是支持删除操作的任意项目计划实体。
msdyn_ExecuteOperationSetV1——使用此 API 在给定操作集内运行所有操作。

以下图表展示数据迁移中涉及的主要步骤。此外，单个步骤列出将用于执行步骤的 API。将在此应用场景中使用大部分与创建相关的 API。

数据迁移涉及以下步骤：

从源导出数据——在实际应用场景中，此步骤将包含多个子步骤。但要简化练习，本应用场景将使用之前讨论的硬编码数据集。数据在 C# 代码示例中硬编码。
创建帐户——您需要先创建帐户，然后再创建项目，以便将项目链接到帐户。您将使用标准 Dynamics 365 SDK 方法创建记录。
创建资源——请在项目迁移开始前确保已在目标系统中创建所有旧系统资源。这些资源将分配给项目团队。在实际应用场景中，资源也可以是系统用户。为了简单起见，您将在目标系统中将每个旧资源创建为联系人。系统将允许您多次重新运行迁移，以便加深理解。要将资源分派给项目，必须创建可预订资源，在系统中将所有联系人创建为可预订资源。旧系统中的所有角色都将映射到可预订资源类别。
创建项目——使用msdyn_CreateProjectV1API 在目标系统中创建项目记录。
应用项目模板——组织可以制定一组应在初始化时应用到每个项目的标准自定义项。您可以使用msdyn_CopyProjectV3API 应用这些自定义项。此步骤标记为可选步骤，下一个单元将详细介绍。已添加此步骤演示 API 的可行用例。
创建团队成员——使用msdyn_CreateTeamMemberV1API 创建与项目关联的团队成员。创建团队成员时，可预订资源记录将链接到 msdyn_projectteam 记录。
创建 OperationSet——OperationsSet 允许将若干计划请求实现为组运行，从而提供事务功能。由于向系统发出的调用较少，因此效率也略高。在此步骤中，您将创建将在后续步骤中使用的新操作集。
添加任务、依赖项和分配——所有与项目关联的任务均从上一步添加到 OperationSet。您还将创建任务依赖项和分配。
运行 OperationSet——将所有任务和相关信息添加到 OperationSet 后，可以使用msdyn_ExecuteOperationSetV1API 运行集合。此 API 将确保运行所有已在集合中定义的操作并返回错误。默认情况下，集合中的所有操作都必须成功才能成功。重复上述步骤直至更多项目可供迁移。

运行数据迁移代码

以下示例展示负责上述应用场景的核心代码。代码需要本节末尾提供的一些额外帮助程序代码。

InitializeLegacyData();
InitializeOrganisationService();

PrintHeader("Create Accounts");
foreach (var legacyAccount in data.Accounts)
{
    CreateAccount(legacyAccount);
}

PrintHeader("Create Resources");
foreach (var legacyContact in data.Resources)
{
    Entity contact = CreateContact(legacyContact);
    CreateBookableResource(legacyContact, contact);
}

PrintHeader("Create Bookable Resource categories");
Entity ProjectManagerResource = CreatePMResource();
Entity TeamMemberResource = CreateTeamMemberResource();


PrintHeader("Create Projects");
foreach (var legacyProject in data.Projects)
{
    Entity project = CreateProject(legacyProject);
    var projectReference = project.ToEntityReference();

    // create team members associated with the project
    foreach (var legacyProjectTeam in data.ProjectTeams
        .Where(x => x.ProjectId == legacyProject.ProjectId))
    {
        CreateTeamMember(
            ProjectManagerResource,
            TeamMemberResource,
            projectReference,
            legacyProjectTeam);
    }

    // Create operation set to include all the tasks, dependencies and assignments
    var description = $"{legacyProject.Name} - {DateTime.Now.ToShortTimeString()}";
    var operationSetId = CallCreateOperationSetAction(project.Id, description);

    // Create tasks and assignment
    foreach (var legacyTask in data.Tasks
        .Where(x => x.ProjectId == legacyProject.ProjectId))
    {
        Entity task = AddTaskToOperationSet(
            projectReference,
            operationSetId,
            legacyTask);

        // Find assignment for the task. To keep the scenario simple
        // there is only one assignment per task.
        var legacyAssignment = data.Assignments
            .FirstOrDefault(x => x.TaskId == legacyTask.TaskId);
        if (legacyAssignment != null)
        {
            AddAssignmentToOperationSet(
                legacyProject,
                project,
                operationSetId,
                legacyTask,
                task,
                legacyAssignment);
        }
    }

    // create task dependencies
    foreach (var legacyDependency in data.Dependencies
        .Where(x => x.ProjectId == legacyProject.ProjectId))
    {
        AddDependencyToOperationSet(
            project,
            operationSetId,
            legacyDependency);
    }

    CallExecuteOperationSetAction(operationSetId);
}

Console.WriteLine("Migration finished. Press any key to continue...");
Console.ReadLine();

观察示例代码运行情况：

项目总工作量根据任务提供的持续时间自动计算。
任务支持分组，其中创建项目计划在 Northwind 转换项目项目计划部分下。
您可在项目记录任务部分的时间线选项卡中查看任务的依赖项。
项目经理设置为项目审批者。

您可以访问此链接 Program.cs 文件中的其他方法。

限制和已知问题

运行数据迁移代码的限制和已知问题包括：

项目计划 API 仅限具有 Microsoft Project 许可证的人员使用。以下人员无法使用 API：
- 应用程序用户
- 系统用户
- 集成用户
- 其他不具有必要许可证的用户
每个 OperationSet 最多包含 100 项操作。
每个用户最多拥有 10 个开放 OperationSets。
Project Operations 项目目前最多支持 500 个任务。
OperationSet 失败状态和失败日志目前不可用。

有关详细信息，请参阅项目和任务的限制和界限。

反馈

此页面是否有帮助？