API de cerca de disponibilitat de recursos

Les organitzacions de servei de camp han de programar el treball, sovint a través d'un servei agent directament pel client. Les reserves solen crear-se en funció dels recursos disponibles per a l'empresa i dels requisits del treball.

Quan utilitzis almenys Dynamics 365 Field Service v8.8.43.51 i Universal Resource Scheduling v3.12.46.21 per programar feina, utilitza l'API msdyn_SearchResourceAvailability per recuperar tots els recursos elegibles per a la feina, així podràs programar-la de manera eficient. En el moment d'escriure això, la v3 és la versió més recent i msdyn_SearchResourceAvailability admet trucades a l'API web.

Nota

Utilitza la versió més recent de l'API, ja que versions antigues podrien utilitzar mètodes d'autenticació obsolets.

Paràmetres d’entrada

Nom	Tipus	Descripció	Necessari	Valor per defecte
Versió	String	El número de versió de l'API identifica la versió de l'API que cal invocar. Segueix el format major.minor.patch. La sol·licitud no ha de contenir el número de versió complet. Si només s'especifica una versió principal, invoca la versió més alta de la versió menor i dels pedaços disponible per a aquesta versió principal. Si s'especifiquen tant la versió principals com la secundària, invoca la versió del pedaç més alta disponible. Si s'esmenten les tres parts de la versió, invoca la versió exacta de l'API especificada.	Sí	-N/A-
IsWebApi	booleà	Posa-ho a True per utilitzar l'assistent d'horari a través de l'API web.	Sí	-N/A-
Requisit	Entitat	Aquest atribut especifica el requisit de recurs per al qual s'està recuperant la disponibilitat de recursos. S'espera que sigui una entitat de tipus msdyn_resourcerequirement . El requisit pot ser un registre preexistent de la base de dades o un creat sobre la marxa amb les restriccions necessàries. L'entitat ha de contenir tots els detalls específics rellevants per a la cerca. El `@odata.type` d'aquesta entitat hauria de ser `Microsoft.Dynamics.CRM.msdyn_requirement`. Els següents atributs importants per omplir: msdyn_fromdate (DateTime): Data de sortida del requisit en format ISO msdyn_todate (DateTime): Requisits fins a la data en format ISO msdyn_remainingduration (enter): la durada restant del requisit en minuts msdyn_duration (enter): la durada total del requisit en minuts	Sí	-N/A-
Configuració	Entitat	L'atribut de configuració ajuda a filtrar encara més els recursos recuperats. Especifica la configuració com a atributs en una bossa d'entitats. El tipus d'entitat no importa. Podeu especificar qualsevol nom lògic d'entitat.	Sí	-N/A-
Especificació de recursos	Entitat	Defineix l'atribut `resourceSpecification` com a atributs dins d'una bossa d'entitats. El `@odata.type` d'aquesta entitat hauria de ser `Microsoft.Dynamics.CRM.expando`.	No	cap

Entitat de la configuració

L'entitat de configuració no és una entitat que existeix a la Dataverse; no obstant això, és una col·lecció de tots els atributs següents que ajuda l'API de planificació Ajudant a filtrar els resultats. Per tant, el @odata.type per a aquesta entitat hauria de ser Microsoft.Dynamics.CRM.expando.

Nom	Tipus	Descripció	Necessari	Valor per defecte
ConsiderSlotsWithLessThanRequiredCapacity	booleà	Definiu-ho com a True si s'ha de tenir en compte una franja horària amb menys de la capacitat necessària (esforç) quan es calculen les franges horàries potencials disponibles al calendari del recurs.	No	Fals
ConsiderSlotsWithLessThanRequiredDuration	booleà	Definiu-ho com a True si s'ha de tenir en compte una franja horària amb una durada inferior a la necessària quan es calculen les franges horàries potencials disponibles al calendari del recurs.	No	Fals
ConsiderSlotsWithOverlappingBooking	booleà	Definiu-ho com a True si s'ha de tenir en compte una franja horària amb reserves superposades a l'hora de calcular les franges horàries potencials disponibles al calendari del recurs.	No	Fals
ConsiderSlotsWithProposedBookings	booleà	Definiu-ho com a True si s'ha de tenir en compte una franja horària amb reserves proposades en calcular les franges horàries disponibles potencials al calendari del recurs.	No	Fals
ConsiderAppointments	booleà	Definiu-ho com a True per a l'API de disponibilitat de recursos de cerca per respectar les cites existents Dataverse com a reserves del recurs, sempre que s'hagi definit la configuració del nivell d'organització i derecurs. Les cites amb l'estat Ocupat o Completat es consideren no disponibles per a operacions de programació.	No	Fals
ConsiderTravelTime	booleà	Definiu-ho com a True si el temps de viatge s'ha de tenir en compte quan es calculen franges horàries potencials al calendari del recurs.	No	Cert
ExcludeResourceCharacteristics	booleà	Configura-ho a True per excloure característiques de recursos per a les franges horàries en resposta.	No	Fals
MovePastStartDateToCurrentDate	booleà	Definiu-ho com a True per moure una data d'inici en el passat a la data actual.	No	Fals
UseRealTimeResourceLocation	booleà	Definiu-ho com a True si s'ha d'utilitzar la ubicació en temps real dels recursos quan es calculen franges horàries potencials al calendari del recurs.	No	Fals
SortOrder	EntityCollection	Especifiqueu l'ordre d'ordenació mitjançant una col·lecció d'entitats. Cada entitat de la col·lecció representa un criteri d'ordenació i només pot ordenar `Resources` a partir de la resposta, però no `TimeSlots`. El `@odata.type` d'aquesta entitat hauria de ser `Microsoft.Dynamics.CRM.expando`. A continuació es mostren els atributs que heu d'emplenar: Name (String): els criteris d'ordenació SortOrder (Integer): la direcció d'ordenació (0 per a ascendent i 1 per a descendent)	No	cap
MaxResourceTravelRadius	Entitat	Aquest atribut especifica el màxim que es pot definir en una entitat. El `@odata.type` d'aquesta entitat hauria de ser `Microsoft.Dynamics.CRM.expando`. A continuació es mostren els atributs que heu d'emplenar: Value (Decimal): el radi Unit (Integer): La unitat de distància. Vegeu el conjunt d'opcions de la unitat msdyn_distance per veure els valors possibles.	No	0 km. Si aquest és el cas, no es retornen recursos per als requisits in situ.
MaxNumberOfResourcesToEvaluate	Enter	Aquest atribut defineix un límit pel nombre de recursos que es consideren per a la sol·licitud.	No	Si aquest atribut no està inclòs a la crida a l'API, el sistema utilitza el Límit de Recuperació de Disponibilitat de Recursos de la definició d'entitat planificable tal com es defineix a la configuració d'Edició per a entitats habilitades. Si s'inclou a la trucada, sobreescriu el límit de recuperació de disponibilitat de recursos definit.
ConsideraPlanificacions	booleà	Configura-ho a Cert si cal tenir en compte els horaris de Outlook. Només disponible a les versions 3.1.0 i posteriors.	No	Fals

Entitat d'especificació de recursos

Nom	Tipus	Descripció	Necessari	Valor per defecte
ResourceTypes	EntityCollection	Aquest atribut especifica el tipus de recurs necessari per al requisit. Utilitza una col·lecció d'entitats per especificar aquest atribut. Cada entitat de la col·lecció representa un tipus de recurs que es pot reservar. El `@odata.type` d'aquesta entitat hauria de ser `Microsoft.Dynamics.CRM.msdyn_resourceType`. Aquest atribut és necessari: Valor (enter): el valor del conjunt d'opcions que representa el tipus de recurs: 1. Genèric 2. Contacte 3. Usuari 4. Equipament 5. Compte 6. Equip humà 7. Instal·lació 8. Grups	No	Tots els tipus de recursos excepte l'equip humà
PreferredResources	EntityCollection	Aquest atribut especifica els recursos preferits per al requisit. Afegeix recursos a aquesta col·lecció d'entitats per assegurar-te que són al capdamunt de la llista de recursos disponibles. Fins i tot els recursos que no formen part de la col·lecció d'entitats estan a la llista, però només després dels recursos preferits.	No	cap
RestrictedResources	EntityCollection	Aquest atribut especifica els recursos que no s'han de tenir en compte per al requisit. Totes les franges de temps d'aquest recurs es filtren de la llista de resultats d'aquesta API.	No	cap
MustChooseFromResources	EntityCollection	Aquest atribut especifica els únics recursos que poden trobar-se a la llista de recursos disponibles. Filtra tots els altres resultats de la llista de sortida.
Restriccions	Entitat	Aquest atribut especifica les restriccions addicionals que s'han d'aplicar a la recuperació dels recursos disponibles.	No	cap
RetrieveResourcesQueryId	Guid	L'identificador de la consulta Recupera recursos.	No	L'identificador de consulta de recursos de recuperació per defecte.
BookedResourceId	Guid	Aquest atribut especifica el tipus de reservat actualment per al requisit.	No	cap

Nota

Utilitza una col·lecció d'entitats d'entitats de recursos reservables per especificar els atributs de recursos Preferits, Restringits i MustChooseFrom . Cada entitat de la col·lecció representa un recurs Preferit, Restringit o MustChooseFrom . Aquest atribut és necessari per a ells:

Valor (Guid): L'ID de recurs reservable del recurs Preferred, Restringit o MustChooseFrom . El @odata.type d'aquesta entitat hauria de ser Microsoft.Dynamics.CRM.msdyn_bookableresource.

Restriccions

Especifica restriccions addicionals mitjançant atributs en aquesta entitat. El tipus d'entitat no importa. Podeu especificar qualsevol nom lògic d'entitat.

Reviseu la consulta Recupera recursos a la configuració del tauler de planificació per identificar quines restriccions es poden aplicar. Per defecte, inclou el següent:

Nom	Tipus	Descripció
Característiques	EntityCollection	Un conjunt de característiques que un recurs qualificat ha de tenir. Cada entrada conté un `characteristic` amb l'ID característic. Opcionalment, inclou un `ratingvalue` amb l'ID del valor de valoració per filtrar recursos per un nivell de competència específic.
Funcions	EntityCollection	Recull d'ID de funció que ha de tenir un recurs qualificat.
Zones de vendes	EntityCollection	Recull d'ID de zones. Cal assignar un recurs qualificat a una de les zones de vendes.
UnspecifiedTerritory	booleà	En combinació amb la restricció de zones de vendes, especifica que cal assignar-ne un de qualificat a una de les zones de vendes o a cap zona de vendes.
OrganizationalUnits	EntityCollection	Col·lecció d'identificadors d'unitats organitzatives. Un recurs qualificat ha de ser membre d'una de les unitats organitzatives especificades.
Teams	EntityCollection	Recull d'ID d'equips. Un recurs qualificat ha de pertànyer a un dels equips (implica que el tipus de recurs sigui un usuari del sistema).
BusinessUnits	EntityCollection	Una col·lecció d'identificadors d'unitats de negoci. Un recurs qualificat ha de pertànyer a una de les unitats de negoci (implica que el recurs sigui un usuari del sistema).

Paràmetres de sortida

Al nivell més alt, la sortida té els quatre paràmetres següents. Els resultats es representen a les col·leccions d'entitats i a les entitats. És possible que les respostes no incloguin tots els atributs descrits aquí, ja que els valors nuls o no s'ometen valors NA de la resposta. Comproveu sempre la presència d'un atribut abans de provar d'accedir-hi.

Nom	Tipus	Descripció
TimeSlots	EntityCollection	Recull de resultats d'un franja horària. Per obtenir més informació, vegeu la secció d'entitats de franja horària .
Recursos	EntityCollection	Recull de resultats de recursos. Els recursos es representen com una col·lecció d'entitats amb els atributs següents: BookableResource (Entity): l'entitat de recurs que es pot reservar que està disponible per al requisit. TotalAvailableTime (Double): el temps total disponible perquè el recurs realitzi el requisit.
Relacionada	Entitat	Els recursos relacionats representen recursos i franges horàries de recursos que no estan directament qualificats per al requisit sol·licitat, però estan relacionats. Per exemple, si un membre de l'equip humà està qualificat per a un requisit, els altres membres d'aquesta equip serien resultats relacionats. Timeslots( EntityCollection): franges horàries dels recursos relacionats. La definició de franges horàries és la mateixa que es descriu a la secció de franges horàries. Resources (EntityCollection): els recursos relacionats. La definició de recursos és la mateixa que es descriu a la definició de l'atribut resources.
Excepcions	Entitat	Aquest atribut conté informació sobre qualsevol excepció que s'hagi produït i informació sobre si i on s'ha truncat la cerca de recursos. Message (String): missatge d'excepció ResourcesTruncatedAt (Integer): si el nombre de recursos supera el límit de recuperació; el nombre on es van truncar els recursos.

Entitat de les franges de temps

Nom	Tipus	Descripció
ID	Guid	Identificador únic de la franja de temps
Tipus	Enter	El tipus de franja horària. Pot ser un dels valors següents: 0: Disponible 1: Programat 2: Desactivat 3: Descans
StartTime	DataHora	Hora d'inici de la franja de temps. Si hi ha viatge per al requisit, aquest moment és l'hora d'inici del viatge. Si no, aquesta vegada és l'hora d'inici del requisit.
ArrivalTime	DataHora	Hora d'arribada de la franja de temps. Si hi ha viatge per al requisit, aquest moment és l'hora d'inici del requisit, després que el viatge s'hagi completat. Si no, és el mateix que l'hora d'inici de la franja horària.
EndTime	DataHora	Hora final de la franja de temps.
Esforç	Enter	Esforç o capacitat del recurs per dur a terme els requisits.
ResourceRequirement	EntityReference	Requisit de recursos per al qual s'estan recuperant les franges de temps.
Potencial	booleà	Un valor booleà que indica si la franja horària pot complir el requisit sol·licitat.
IsDuplicate	booleà	Valor booleà que indica si la franja horària és duplicada.
AllowOverlapping	booleà	Un valor booleà que indica si es permet el solapament.
Recurs	Entitat	Recurs al qual pertany la franja horària. Per obtenir més informació, vegeu el recurs de la franja horària.
Ubicació	Entitat	La ubicació té tres atributs: Ubicació (entitat): Té dos atributs: Latitud Longitud WorkLocation (Integer): Té tres atributs: Al lloc. Els requisits in situ exclouen els tipus de recursos de conjunt i instal·lació dels resultats. Facilitat Agnòstic d'ubicació LocationSourceSlot (Integer): la font de la informació d'ubicació té tres atributs: Comú Entitat GPS personalitzada Auditoria mòbil
Viatges	Entitat	Aquesta entitat conté detalls sobre el temps de desplaçament i la informació a distància d'un període de temps. Els següents són els atributs: Distància (doble): la distància de viatge TravelTime (Double): el temps de viatge en minuts. DistanceFromStartLocation (Double): la distància des de la ubicació inicial del recurs. DistanceFromEndLocation (Double): la distància des de la ubicació final del recurs. DistanceMethodSourceSlot (Enter): La font o tipus de càlcul dels valors de la distància Servei de mapes En línia recta
Següent	Entitat	Aquesta entitat conté detalls sobre el temps de viatge i la distància a la propera reserva de la franja horària. NextScheduleLocation (Entity): la ubicació de la reserva següent. L'entitat té dos atributs: Latitud Longitud NextScheduleTravelTime (Integer): el temps de viatge a la següent reserva en minuts.
Disponibilitat	Entitat	Informació de disponibilitat detallada d'un franja horària. Aquesta entitat s'utilitza amb grups de temps. AvailableIntervals (EntityCollection): Una col·lecció d'intervals disponibles. Cada entitat d'aquesta col·lecció conté detalls sobre un interval de grup de temps. StartTime (DateTime): l'hora d'inici. ArrivalTime (DateTime): l'hora d'arribada. EndTime (DateTime): l'hora d'acabament. TimeGroupId (DateTime): l'identificador del grup horari. TimeGroupDetailStartTime (DateTime): l'hora d'inici del grup de temps. TimeGroupDetailEndTime (DateTime): l'hora de finalització del grup horari. TotalAvailableDuration (Double): la durada total disponible en minuts. TotalAvailableTime (Double): el temps total disponible que té un recurs en un dia (en minuts).
TimeGroup	Entitat	Detalls sobre un grup de temps. TimeGroupId (Guid): l'identificador del grup de temps. TimeGroupDetail (EntityReference): Una referència d'entitat al detall del grup de temps. TimeGroupDetailStartTime (DateTime): l'hora d'inici del detall del grup horari. TimeGroupDetailEndTime (DateTime): l'hora de finalització dels detalls del grup de temps.

Propina

Quan creïs reserves utilitzant l'API, utilitza el camp Potencial descrit a la taula. Si no utilitzeu aquest camp, pot provocar reserves superposades o inadequades.

Recurs de la franja de temps

Nom	Tipus	Descripció
Recurs	EntityReference	Referència d'entitat al recurs reservable.
ResourceGroup	EntityReference	Referència d'entitat al grup de recursos reservable.
Unitat de negoci	EntityReference	Referència d'entitat a la unitat de negoci.
OrganizationalUnit	EntityReference	Referència d'entitat a la unitat organitzativa.
ResourceType	Enter	El tipus de recurs. Vegeu l'atribut ResourceType de l'entitat BookableResource per obtenir els valors possibles.
PoolId	Guid	L'identificador del conjunt del qual és membre el recurs durant la franja horària.
CrewId	Guid	L'identificador del dotació del qual el recurs és membre durant la franja horària.
Característiques	EntityCollection	Les característiques dels recursos que es poden reservar. Cada entitat de la col·lecció conté entitats amb característiques i informació de qualificació. Characteristic (EntityReference): Una referència d'entitat a la característica. RatingId (Guid) L'identificador de classificació de la característica. RatingName (String): el nom de la classificació. RatingValue (Integer): el valor de classificació.
HasStartLocation	booleà	Un valor booleà que indica si el recurs té una ubicació d'inici.
HasEndLocation	booleà	Un valor booleà que indica si el recurs té una ubicació d'acabament.
Correu	String	L'adreça electrònica del recurs.
El número de telèfon	String	Número de telèfon del recurs.
ImagePath	String	El camí a la imatge del recurs.
CalendarId	Guid	L'id. del calendari del recurs.

Exemples

En aquest exemple, utilitzes la versió 3 de l'API de l'assistent d'horaris, que admet trucades a l'API web, per a un requisit amb una durada de 60 minuts. Utilitzant l'atribut settings , filtres els resultats. Consideres dos tipus de recursos per als resultats finals: 1 i 2 (és a dir, genèric i contacte).

{
    "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"
                }
            ]
        }
    }
}

L'exemple següent demostra l'ús adequat de les col·leccions d'entitats. En aquest cas, especifica 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"
                }
            ]
        }
    }
}

Comentaris

Us ha resultat útil aquesta pàgina?

Last updated on 2026-04-07