搜索资源可用性 API

现场服务组织需要安排工作，通常由客户直接通过服务代理来安排。预订通常基于公司可用的资源和工作的要求创建。

当你至少使用Dynamics 365 Field Service v8.8.43.51 和 Universal Resource Scheduling v3.12.46.21 来调度工作时，使用 msdyn_SearchResourceAvailability API 获取所有符合条件的资源，以便高效调度工作。撰写本文时，v3是最新版本 msdyn_SearchResourceAvailability ，支持Web API调用。

Note

使用最新版本的 API，因为旧版本可能会使用已废弃的认证方法。

输入参数

Name	类型	说明	必选	Default
版本	String	API 的版本号标识应该调用的 API 的版本。它采用 major.minor.patch 格式。请求不必包含完整的版本号。如果只指定了一个主要版本，它会调用该主要版本可用的最高次要版本和修补程序版本。如果同时指定了主要版本和次要版本，则调用可用的最高修补程序版本。如果版本的所有三个部分都被提及，将调用指定 API 的确切版本。	Yes	-不适用-
IsWebApi	布尔	设置为 True ，通过网页 API 使用排班助手。	Yes	-不适用-
要求	实体	此属性指定正在为其检索资源可用性的资源要求。它应该是 msdyn_resourcerequirement 类型的实体。要求可以是数据库中预先存在的记录，也可以是带有必要约束的动态创建的记录。实体应包含与您的搜索相关的所有细节。该实体的`@odata.type`应为`Microsoft.Dynamics.CRM.msdyn_requirement`。以下是一些要填充的重要属性： msdyn_fromdate (DateTime)：ISO 格式的要求的开始日期 msdyn_todate (DateTime)：ISO 格式的要求的结束日期 msdyn_remainingduration (Integer)：要求的剩余持续时间（以分钟为单位） msdyn_duration (Integer)：要求的总持续时间（以分钟为单位）	Yes	-不适用-
Settings	实体	settings 属性帮助进一步筛选检索到的资源。在实体袋中指定属性设置。实体的类型无关紧要。您可以指定任何实体逻辑名称。	Yes	-不适用-
ResourceSpecification	实体	将属性定义 `resourceSpecification` 为实体袋中的属性。该实体的`@odata.type`应为`Microsoft.Dynamics.CRM.expando`。	No	没有

设置实体

设置实体不是存在于 Dataverse 中的实体；但是，它是以下帮助日程安排助理 API 筛选结果的所有属性的集合。因此，该实体的@odata.type应为Microsoft.Dynamics.CRM.expando。

Name	类型	说明	必选	Default
ConsiderSlotsWithLessThanRequiredCapacity	布尔	如果在计算资源日历上的潜在可用时隙时应考虑产能（工作量）小于所需产能的时隙，则将此值设置为 True。	No	假
ConsiderSlotsWithLessThanRequiredDuration	布尔	如果在计算资源日历上的潜在可用时隙时应考虑持续时间小于所需持续时间的时隙，则将此值设置为 True。	No	假
ConsiderSlotsWithOverlappingBooking	布尔	如果在计算资源日历上的潜在可用时隙时应考虑存在重叠预订的时隙，则将此值设置为 True。	No	假
ConsiderSlotsWithProposedBookings	布尔	如果在计算资源日历上的潜在可用时隙时应考虑存在建议预订的时隙，则将此值设置为 True。	No	假
ConsiderAppointments	布尔	将此设置为 True 可以让搜索资源可用性 API 采用现有 Dataverse 约会作为资源预订，前提是已设定组织和资源级别设置。状态为忙碌或已完成的预约被视为无法安排运营。	No	假
ConsiderTravelTime	布尔	如果在计算资源日历上的潜在时隙时应考虑旅行时间，则将此值设置为 True。	No	是
排除资源特征	布尔	将此设置为 True ，以排除响应时隙的资源特性。	No	假
MovePastStartDateToCurrentDate	布尔	将此值设置为 True 以将过去的开始日期移到当前日期。	No	假
UseRealTimeResourceLocation	布尔	如果在计算资源日历上的潜在时隙时应考虑资源的实时位置，则将此值设置为 True。	No	假
SortOrder	EntityCollection	使用实体集合指定排序顺序。集合中的每个实体代表一个排序条件，并且只能根据响应进行排序 `Resources` ，而不能 `TimeSlots`。该实体的`@odata.type`应为`Microsoft.Dynamics.CRM.expando`。以下是需要填充的属性： Name (String)：排序条件 SortOrder (Integer)：排序方向（0 为升序，1 为降序）	No	没有
MaxResourceTraiusRadius	实体	此属性指定可以在实体中定义的最大值。该实体的`@odata.type`应为`Microsoft.Dynamics.CRM.expando`。以下是需要填充的属性： Value (Decimal)：半径 Unit (Integer)：距离单位。请参见 msdyn_distance 单位选项集了解可能的值。	No	0 千米。如果是这种情况，则不会为现场要求返回任何资源。
MaxNumberOfResourcesToMaxluate	Integer	此属性定义对请求考虑的资源数量的限制。	No	如果该属性未包含在 API 调用中，系统将根据启用实体编辑设置中定义的可调度实体定义的资源可用性检索限制。如果包含在调用中，它将覆盖定义的资源可用性检索限制。
ConsiderOutlookSchedules	布尔	如果需要考虑Outlook的排程，请将此设置为True。仅在3.1.0及以上版本中提供。	No	假

资源规格实体

Name	类型	说明	必选	Default
ResourceTypes	EntityCollection	此属性指定要求所需的资源类型。使用实体集合来指定该属性。集合中的每个实体代表一个可预订资源类型。该实体的`@odata.type`应为`Microsoft.Dynamics.CRM.msdyn_resourceType`。该属性是必需的： Value (Integer)：代表资源类型的选项集值： 1- 通用 2- 联系人 3- 用户 4- 设备 5- 客户 6- 班组 7- 设施 8- 池	No	除班组外的所有资源类型
PreferredResources	EntityCollection	此属性指定要求的首选资源。向该实体集合添加资源，确保它们位列可用资源列表的顶端。即使是不属于实体集合的资源也会在列表中，但只在首选资源之后。	No	没有
RestrictedResources	EntityCollection	此属性指定不应为要求考虑的资源。该资源的所有时隙都会从该API的结果列表中被过滤掉。	No	没有
MustChooseFromResources	EntityCollection	此属性指定可以进入可用资源列表的资源。它将从输出列表中筛掉所有其他结果。
约束	实体	此属性指定应该应用于可用资源检索的其他约束。	No	没有
RetrieveResourcesQueryId	Guid	检索资源查询的 ID。	No	默认检索资源查询 ID。
BookedResourceId	Guid	此属性指定当前为要求预订的资源。	No	没有

Note

使用一个可预订资源实体集合来指定优先、受限和 必须选择的 资源属性。集合中的每个实体代表一个优先资源、受限资源或 必须选择资源 。该属性对它们来说是必需的：

价值（Guid）：首选、受限或 MustChooseFrom 资源的可预订资源ID。该实体的@odata.type应为Microsoft.Dynamics.CRM.msdyn_bookableresource。

约束

通过该实体中的属性指定额外的约束。实体的类型无关紧要。您可以指定任何实体逻辑名称。

查看日程安排板设置上的检索资源查询来确定可能适用的约束。默认情况下，它包含：

Name	类型	说明
特征	EntityCollection	一组合格资源必须具备的特征。每个条目都包含带有特征ID的a `characteristic` 。可选地，可以添加带有评级值ID的A `ratingvalue` ，以按具体熟练度过滤资源。
角色	EntityCollection	符合条件的资源必须具有的角色 ID 的集合。
区域	EntityCollection	区域 ID 的集合。符合条件的资源必须被分配到其中一个区域。
UnspecifiedTerritory	布尔	结合区域约束，指定必须将符合条件的人员分配到区域之一或不分配。
OrganizationalUnits	EntityCollection	部门 ID 的集合。符合条件的资源必须是其中一个指定部门的成员。
Teams	EntityCollection	团队 ID 的集合。符合条件的资源必须属于其中一个团队（这意味着资源类型是系统用户）。
BusinessUnits	EntityCollection	一组业务单元ID集合。符合条件的资源必须属于其中一个业务部门（这意味着资源是系统用户）。

输出参数

在最高级别，输出具有以下四个参数。结果以实体集合和实体表示。响应可能不包括此处所述的所有属性，因为忽略了响应中的空值或非 NA 值。在尝试访问某个属性之前，请始终检查它是否存在。

Name	类型	说明
TimeSlots	EntityCollection	时隙结果的集合。有关详细信息，请参阅时隙实体部分。
Resources	EntityCollection	资源结果的集合。资源表示为具有以下属性的实体集合： BookableResource (Entity)：可用于要求的可预订资源实体。 TotalAvailableTime (Double)：资源执行要求的总可用时间。
相关	实体	相关资源表示没有直接符合所请求的要求但是相关的资源及资源的时隙。例如，如果某班组成员符合某个要求，该班组的其他成员将是相关结果。 Timeslots (EntityCollection)：相关资源的时隙。时隙的定义与时隙一节中所述的定义相同。 Resources (EntityCollection)：相关资源。资源的定义与资源属性定义中所述的相同。
例外	实体	此属性包含有关发生的任何异常的信息，以及有关资源搜索是否以及在何处截断的信息。 Message (String)：异常消息 ResourcesTruncatedAt (Integer)：如果资源数量超过检索限制；资源被截断的数量。

时隙实体

Name	类型	说明
ID	Guid	时隙的唯一标识符
类型	Integer	时间段的类型。它可以是以下值之一： 0：有空 1：已计划 2：休假 3：休息
StartTime	DateTime	时隙的开始时间。如果有旅行要求，这段时间就是旅行开始时间。如果没有，这个时间点就是要求的开始时间。
ArrivalTime	DateTime	时隙的到达时间。如果有出差，这段时间就是出差完成后开始的时间。如果没有，它与时隙的开始时间相同。
EndTime	DateTime	时隙的结束时间。
Effort	Integer	资源执行要求的工作量或产能。
ResourceRequirement	EntityReference	在为其检索时隙的资源要求。
潜力	布尔	一个布尔值，指示时隙是否有可能满足请求的要求。
IsDuplicate	布尔	一个布尔值，指示时隙是否是重复项。
AllowOverlapping	布尔	指示是否允许重叠的布尔值。
Resource	实体	时隙所属的资源。有关详细信息，请参阅时隙资源。
Location	实体	location 有三个属性： Location (Entity)：它具有两个属性 - 纬度经度 WorkLocation (Integer)：它具有三个属性 - 现场。现场要求从结果中排除池和设施资源类型。设施位置无关 LocationSourceSlot (Integer)：位置信息的来源具有三个属性 - 常见自定义 GPS 实体移动审核
出差	实体	此实体包含某个时隙的旅行时间和距离信息的详细信息。以下是属性： Distance (Double)：旅行距离 TravelTime (Double)：以分钟为单位的旅行时间。 DistanceFromStartLocation (Double)：与资源开始位置之间的距离。 DistanceFromEndLocation (Double)：与资源结束位置之间的距离。 DistanceMethodSourceSlot （整数）：距离值的源或计算类型地图服务直线距离
下一步	实体	此实体包含有关旅行时间和到下一个时隙预订的距离的详细信息。 NextScheduleLocation (Entity)：下一个预订的位置。此实体具有两个属性：纬度经度 NextScheduleTravelTime (Integer)：以分钟为单位的到达下一个预订的旅行时间。
可用性	实体	时隙的详细可用性信息。该实体用于时间组。 AvailableIntervals (EntityCollection)：可用间隔的集合。此集合中的每个实体都包含有关时间组间隔的详细信息。 StartTime (DateTime)：开始时间。 ArrivalTime (DateTime)：到达时间。 EndTime (DateTime)：结束时间。 TimeGroupId (DateTime)：时间组 ID。 TimeGroupDetailStartTime (DateTime)：时间组开始时间。 TimeGroupDetailEndTime (DateTime)：时间组结束时间。 TotalAvailableDuration (Double)：以分钟为单位的总可用持续时间。 TotalAvailableTime (Double)：资源在一天内的总可用时间（以分钟为单位）。
TimeGroup	实体	有关时间组的详细信息。 TimeGroupId (Guid)：时间组 ID。 TimeGroupDetail (EntityReference)：对时间组详细信息的实体引用。 TimeGroupDetailStartTime (DateTime)：时间组详细信息开始时间。 TimeGroupDetailEndTime (DateTime)：时间组详细信息结束时间。

小窍门

使用API创建预订时，请使用表中描述的潜在字段。不使用该字段可能会导致重叠或不合适的预订。

时隙资源

Name	类型	说明
Resource	EntityReference	对可预订资源的实体引用。
ResourceGroup	EntityReference	对可预订资源组的实体引用。
BusinessUnit	EntityReference	对业务部门的实体引用。
OrganizationalUnit	EntityReference	对部门的实体引用。
资源类型	Integer	资源类型。可能的值请参见 BookableResource 实体上的 ResourceType 属性。
PoolId	Guid	时隙持续时间内的资源所属池的 ID。
CrewId	Guid	时隙持续时间内的资源所属班组的 ID。
特征	EntityCollection	可预订资源的特征。集合中的每个实体都包含具有特征和评级信息的实体。 Characteristic (EntityReference)：对特征的实体引用。 RatingId (Guid) 特征的评级 ID。 RatingName (String)：评级名称。 RatingValue (Integer)：评级值。
HasStartLocation	布尔	指示资源是否具有开始位置的布尔值。
HasEndLocation	布尔	指示资源是否具有结束位置的布尔值。
Email	String	资源的电子邮件地址。
手机	String	资源的电话号码。
ImagePath	String	资源的图像的路径。
CalendarId	Guid	资源的日历 ID。

例子

在这个例子中，你使用了支持网页API调用的排程助手API第3版，满足一个时长为60分钟的需求。通过使用属性 settings ，你会过滤结果。你考虑两种资源类型作为最终结果：1和2（换句话说，通用和接触）。

{
    "Version": "4",
    "IsWebApi": true,
    "Requirement": {
        "msdyn_fromdate": "2021-07-14T00:00:00Z",
        "msdyn_todate": "2021-07-15T23:59:00Z",
        "msdyn_remainingduration": 60,
        "msdyn_duration": 60,
        "msdyn_TimeGroup@odata.bind": "/msdyn_timegroups(c3dc79ea-d12f-ee11-9cc9-000d3a745a58)",
        "@odata.type": "Microsoft.Dynamics.CRM.msdyn_resourcerequirement"
    },
    "Settings": {
        "ConsiderSlotsWithProposedBookings": false,
        "MovePastStartDateToCurrentDate": true,
        "@odata.type": "Microsoft.Dynamics.CRM.expando"
    },
    "ResourceSpecification": {
        "@odata.type": "Microsoft.Dynamics.CRM.expando",
        "ResourceTypes@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
        "ResourceTypes": [
            {
                "@odata.type": "Microsoft.Dynamics.CRM.expando",
                "value": "1"
            },
            {
                "@odata.type": "Microsoft.Dynamics.CRM.expando",
                "value": "2"
            }
        ],
        "Constraints": {
            "@odata.type": "Microsoft.Dynamics.CRM.expando",
            "Characteristics@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
            "Characteristics": [
                {
                    "@odata.type": "Microsoft.Dynamics.CRM.expando",
                    "characteristic": {
                        "@odata.type": "Microsoft.Dynamics.CRM.expando",
                        "value": "67387f9f-12e2-ec11-bb43-000d3aed25f7"
                    },
                    "ratingvalue": {
                        "@odata.type": "Microsoft.Dynamics.CRM.expando",
                        "value": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
                    }
                }
            ],
            "Territories@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
            "Territories": [
                {
                    "@odata.type": "Microsoft.Dynamics.CRM.expando",
                    "value": "cc19f004-4483-ee11-8178-000d3a5c32c3"
                }
            ],
            "Roles@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
            "Roles": [
                {
                    "@odata.type": "Microsoft.Dynamics.CRM.expando",
                    "value": "76998e42-744c-f011-877d-6045bdfb899e"
                }
            ]
        }
    }
}

以下示例演示了实体集合的正确用法。在这种情况下，它指定了 MustChooseFromResources。

{
    "Version": "4",
    "IsWebApi": true,
    "Requirement": {
        "msdyn_fromdate": "2021-07-14T00:00:00Z",
        "msdyn_todate": "2021-07-15T23:59:00Z",
        "msdyn_remainingduration": 60,
        "msdyn_duration": 60,
        "msdyn_latitude": 47.64807,
        "msdyn_longitude": -122.41249,
        "msdyn_worklocation": 690970000,
        "msdyn_TimeGroup@odata.bind": "/msdyn_timegroups(c3dc79ea-d12f-ee11-9cc9-000d3a745a58)",
        "@odata.type": "Microsoft.Dynamics.CRM.msdyn_resourcerequirement"
    },
    "Settings": {
        "ConsiderSlotsWithProposedBookings": false,
        "MovePastStartDateToCurrentDate": true,
        "MaxNumberOfResourcesToEvaluate":500,
        "ConsiderTravelTime": true,
        "MaxResourceTravelRadius": {
            "Value": 20,
            "Unit" : 192350000,
            "@odata.type": "Microsoft.Dynamics.CRM.expando"
        },
        "@odata.type": "Microsoft.Dynamics.CRM.expando"
    },
    "ResourceSpecification": {
        "@odata.type": "Microsoft.Dynamics.CRM.expando",
        "ResourceTypes@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
        "ResourceTypes": [
            {
                "@odata.type": "Microsoft.Dynamics.CRM.expando",
                "value": "1"
            },
            {
                "@odata.type": "Microsoft.Dynamics.CRM.expando",
                "value": "2"
            }
        ],
        "MustChooseFromResources@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
        "MustChooseFromResources": [
            {
                "@odata.type": "Microsoft.Dynamics.CRM.expando",
                "value": "2145a982-f718-ed11-b83e-0022482d79c8"
            }
        ],
        "Constraints": {
            "@odata.type": "Microsoft.Dynamics.CRM.expando",
            "Characteristics@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
            "Characteristics": [
                {
                    "@odata.type": "Microsoft.Dynamics.CRM.expando",
                    "characteristic": {
                        "@odata.type": "Microsoft.Dynamics.CRM.expando",
                        "value": "67387f9f-12e2-ec11-bb43-000d3aed25f7"
                    },
                    "ratingvalue": {
                        "@odata.type": "Microsoft.Dynamics.CRM.expando",
                        "value": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
                    }
                }
            ],
            "Territories@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
            "Territories": [
                {
                    "@odata.type": "Microsoft.Dynamics.CRM.expando",
                    "value": "cc19f004-4483-ee11-8178-000d3a5c32c3"
                }
            ]
        }
    }
}

反馈

此页面是否有帮助？

Last updated on 2026-05-01