Sök-API för tillgänglighet av resurser

Field Service-organisationer behöver schemalägga arbete, ofta via en serviceagent direkt av kunden. Bokningar skapas vanligtvis baserat på de resurser som finns tillgängliga för företaget och på arbetets krav.

När du använder minst Dynamics 365 Field Service v8.8.43.51 och Universal Resource Scheduling v3.12.46.21 för att schemalägga arbete, använd msdyn_SearchResourceAvailability API för att hämta alla berättigade resurser för jobbet, så att du effektivt kan schemalägga arbetet. Vid skrivande stund är v3 den senaste versionen av msdyn_SearchResourceAvailability och stöder webb-API-anrop.

Anmärkning

Använd den senaste versionen av API:et eftersom äldre versioner kan använda föråldrade autentiseringsmetoder.

Indataparametrar

Name	Type	Description	Krävs	Default
Version	Sträng	Versionsnumret för API identifierar den version av API som ska anropas. Den följer formatet major.minor.patch. Förfrågan behöver inte innehålla det fullständiga versionsnumret. Om endast en större version anges, anropar den högsta mindre versionen och den tillgängliga programkorrigeringsversionen för den huvudversionen. Om du anger både huvudversioner och mindre versioner startas den högsta tillgängliga versionen av programkorrigeringen. Om alla tre delarna i versionen anges anropar den exakta versionen av API:et.	Yes	Inte tillgänglig
IsWebApi	Boolean	Ställ in på True för att använda schemaassistenten via webb-API:et.	Yes	Inte tillgänglig
Behov	Enhet	Det här attributet anger resurskraven för vilket resurstillgänglighet hämtas. Detta förväntas vara en entitet av typen msdyn_resourcerequirement. Kravet kan vara en befintlig post från databasen, eller en som skapas direkt med de begränsningar som krävs. Entiteten ska innehålla alla relevanta uppgifter för sökningen. `@odata.type` för denna entitet bör vara `Microsoft.Dynamics.CRM.msdyn_requirement`. Följande viktiga attribut ska fyllas i: msdyn_fromdate (DateTime): Krav är från datum i ISO-format msdyn_todate (DateTime): Krav är till datum i ISO-format msdyn_remainingduration (Integer): Den återstående varaktigheten för kravet i minuter msdyn_duration (Integer): Den totala varaktigheten för kravet i minuter	Yes	Inte tillgänglig
Settings	Enhet	Med hjälp av inställningsattributet filtreras de hämtade resurserna ytterligare. Ange inställningar som attribut i en entitetspåse. Typen av entitet spelar ingen roll. Du kan ange det logiska namnet på en entitet.	Yes	Inte tillgänglig
ResourceSpecification	Enhet	Definiera attributet `resourceSpecification` som attribut i en entitetspåse. `@odata.type` för denna entitet bör vara `Microsoft.Dynamics.CRM.expando`.	No	Ingen

Inställningsentitet

Inställningsentiteten är inte en entitet som finns i Dataverse: men det är en samling med alla följande attribut som hjälper schemaläggningsassistenten att API-filterresultat. Därför bör @odata.type för denna entitet vara Microsoft.Dynamics.CRM.expando.

Name	Type	Description	Krävs	Default
ConsiderSlotsWithLessThanRequiredCapacity	Boolean	Ange detta som True om du bör använda ett tidslucka som inte har den kapacitet som krävs (insats) när du beräknar möjliga tillgängliga tidsluckor i resursens kalender.	No	Falsk
ConsiderSlotsWithLessThanRequiredDuration	Boolean	Ange detta som True om du bör använda ett tidslucka som inte har den varaktighet som krävs när du beräknar möjliga tillgängliga tidsluckor i resursens kalender.	No	Falsk
ConsiderSlotsWithOverlappingBooking	Boolean	Ange detta som True om du bör använda en tidslucka som inte har överlappa bokning som krävs när du beräknar möjliga tillgängliga tidsluckor i resursens kalender.	No	Falsk
ConsiderSlotsWithProposedBookings	Boolean	Ange detta som True om du bör använda en tidslucka som inte har förslagna bokning som krävs när du beräknar möjliga tillgängliga tidsluckor i resursens kalender.	No	Falsk
ConsiderAppointments	Boolean	Ange detta som True för sökresurs tillgänglighet API för att respektera befintliga Dataverse möten som bokningar på resursen, förutsatt att inställningar för organisation och resursnivå har ställts in. Bokningar med statusen Upptagen eller Avslutad anses vara otillgängliga för att schemalägga operationer.	No	Falsk
ConsiderTravelTime	Boolean	Ange detta som True om restid bör beaktas vid beräkning av potentiella tidsluckor på resursens kalender.	No	Sant
ExkluderaResursEgenskaper	Boolean	Sätt detta till True för att utesluta resursegenskaper för tidsluckorna som svarar.	No	Falsk
MovePastStartDateToCurrentDate	Boolean	Ange detta till True för att flytta ett tidigare datum till det aktuella datumet.	No	Falsk
UseRealTimeResourceLocation	Boolean	Ange detta som True om resursens realtidsplats ska användas vid beräkning av potentiella tidsluckor i resursens kalender.	No	Falsk
SortOrder	EntityCollection	Ange sorteringsordningen med hjälp av en entitetssamling. Varje entitet i samlingen representerar ett sorteringsvillkor och kan bara sortera `Resources` från svaret, men inte `TimeSlots`. `@odata.type` för denna entitet bör vara `Microsoft.Dynamics.CRM.expando`. Följande attribut måste fyllas i: Namn (Sträng): Sorteringsvillkor SortOrder (Heltal): Sorteringsriktningen (0 för stigande och 1 för fallande)	No	Ingen
MaxResourceTravelRadius	Enhet	Det här attributet anger det maximala kan definieras i en entitet. `@odata.type` för denna entitet bör vara `Microsoft.Dynamics.CRM.expando`. Följande attribut måste fyllas i: Värde (Decimal): radius Enhet (Heltal): Enhetens längd. Se msdyn_distance enhetsvärden alternativuppsättning information om möjliga värden.	No	0 km. Om så är fallet returneras inga resurser för krav på plats.
MaxNumberOfResourcesToEvaluate	Heltal	Det här attributet definierar en begränsning för antalet resurser som övervägs för förfrågan.	No	Om detta attribut inte ingår i API-anropet använder systemet Resource Availability Retrieval Limit från schemalagbar entitetsdefinition som definierats i Redigera inställningar för aktiverade enheter. Om det ingår i anropet skriver det över den definierade hämtningsgränsen för resurstillgänglighet.
ConsiderOutlookSchedules	Boolean	Ställ in detta till True om scheman från Outlook bör beaktas. Endast tillgänglig i versioner 3.1.0 och senare.	No	Falsk

Entiteten Resursspecifikation

Name	Type	Description	Krävs	Default
ResourceTypes	EntityCollection	Det här attributet anger vilken resurstyp som krävs för kravet. Använd en entity collection för att specificera detta attribut. Varje entitet i samlingen motsvarar ett bokningsbar resurstyp. `@odata.type` för denna entitet bör vara `Microsoft.Dynamics.CRM.msdyn_resourceType`. Denna egenskap krävs: Värde (Heltal): Alternativuppsättning värde som motsvarar resurstypen: 1- Generisk 2- Kontakt 3- Användare 4- Utrustning 5- Konto 6- Medarbetare 7- Lokal 8- Pooler	No	Alla resurstyper utom arbetslag
PreferredResources	EntityCollection	Det här attributet anger önskade resurser för kravet. Lägg till resurser i denna entitetssamling för att säkerställa att de ligger högst upp på listan över tillgängliga resurser. Även resurser som inte ingår i entitetssamlingen finns på listan, men bara efter de föredragna resurserna.	No	Ingen
RestrictedResources	EntityCollection	Det här attributet anger resurser som inte ska beaktas för kravet. Alla tidsluckor för denna resurs filtreras bort från listan över resultat från detta API.	No	Ingen
MustChooseFromResources	EntityCollection	Det här attributet anger de enda resurser som kan finnas i listan över tillgängliga resurser. Alla andra resultat filtreras bort från utdatalistan.
Begränsningar	Enhet	Det här attributet anger vilka ytterligare begränsningar som ska tillämpas på hämtningen av tillgängliga resurser.	No	Ingen
RetrieveResourcesQueryId	GUID	ID:t för redigera resursfrågan för hämtning.	No	ID för standardfråga för hämtning av resurs.
BookedResourceId	GUID	Det här attributet anger vilken resurs som för närvarande krävs för kravet.	No	Ingen

Anmärkning

Använd en enhetssamling av bokningsbara resursenheter för att specificera attributen Föredragen, Begränsad och MustChooseFrom . Varje enhet i samlingen representerar en Föredragen, Begränsad eller MåsteVäljaFrån-resurs . Denna egenskap krävs för dem:

Value (Guid): Den bokbara resurs-ID:n för Preferred, Restricted eller MustChooseFrom-resursen . @odata.type för denna entitet bör vara Microsoft.Dynamics.CRM.msdyn_bookableresource.

Begränsningar

Specificera ytterligare begränsningar genom attribut i denna entitet. Typen av entitet spelar ingen roll. Du kan ange det logiska namnet på en entitet.

Läs Hämta resursfråga i inställningarna för schemaläggningstavlan och identifiera vilka begränsningar som kan gälla. Det innehåller som standard följande fält:

Name	Type	Description
Karaktäristika	EntityCollection	En samling egenskaper som en kvalificerad resurs måste ha. Varje post innehåller en med karaktäristiskt `characteristic` ID. Eventuellt, inkludera en `ratingvalue` med betygsvärde-ID för att filtrera resurser efter en specifik färdighetsnivå.
Roller	EntityCollection	En samling med roll-ID:er som en kvalificerad resurs måste ha.
Områden	EntityCollection	En samling med områdes-ID. En kvalificerad resurs måste tilldelas ett område.
UnspecifiedTerritory	Boolean	I kombination med områdesbegränsningen anger du att en kvalificerad person måste tilldelas ett av områdena eller inget område alls.
OrganizationalUnits	EntityCollection	En samling med ID:n för organisationsenheter. En kvalificerad resurs måste vara medlem i en av de angivna organisationsenheterna.
Teams	EntityCollection	En samling med team-ID. En kvalificerad resurs måste tillhöra något av teamen (det förutsätts att resurstypen är en systemanvändare).
BusinessUnits	EntityCollection	En samling affärsenhets-ID:n. En kvalificerad resurs måste tillhöra något av affärsenheter (det förutsätts att resursen är en systemanvändare).

Utdataparametrar

På den högsta nivån har utdata följande fyra parametrar. Resultaten representeras i entitetssamlingar och entiteter. Svaren kanske inte innehåller alla attribut som beskrivs här som null-värden eller så utesluts inte NA-värden från svaret. Kontrollera alltid om ett attribut finns där innan du försöker komma åt det.

Name	Type	Description
TimeSlots	EntityCollection	En samling med resultat för tidslucka. Mer information finns i avsnittet om entitet för tidslucka .
Resources	EntityCollection	En samling med resursresultat. Resurser representeras som en samling entiteter med följande attribut: BookableResource (Entittet): Den bokningsbara resursentitet som är tillgänglig för kravet. TotalAvailableTime (Dubbel): Den totala tillgängliga tiden för resursen att utföra kravet.
Relaterade	Enhet	Relaterade resurser representerar resurser och tidsluckor för resurser som inte är direkt kvalificerade för det begärda kravet men som är relaterade. Om till exempel en medlem kvalificerar sig för ett krav blir de andra medlemmarna i programmet relaterade resultat. Tidsluckor (EntityCollection): Tidsluckor för relaterade resurser. Definitionen för tidsluckor är samma som i beskrivningen i avsnittet med tidsluckor. Resurser (EntityCollection): De relaterade resurserna. Definitionen av resurser är densamma som i resursattributsdefinitionen.
Undantag	Enhet	Det här attributet innehåller information om eventuella undantag och information om om och var resurssökningen trunkerades. Meddelande (sträng): Undantagsmeddelande ResourcesTruncatedAt (Heltal): Om antalet resurser överskred hämtningsgränsen; antalet där resurserna var avkortade.

Entitet för tidsluckor

Name	Type	Description
ID	GUID	Unik identifierare för tidsluckan
Type	Heltal	Den typen av tidslucka. Det kan vara något av följande värden: 0: Tillgängliga 1: Schemalagda 2: Av 3: Brytning
StartTime	Datum/tid	Starttiden för tidsluckan. Om det krävs resor är denna tid starttiden för resan. Om inte, är denna tid starttiden för kravet.
ArrivalTime	Datum/tid	Ankomsttiden för tidsluckan. Om det finns resor för kravet, är denna tid starttiden för kravet, efter att resan är slutförd. I annat fall är det samma som vid starttiden för tidsluckan.
EndTime	Datum/tid	Sluttiden för tidsluckan.
Effort	Heltal	Resursens insats eller kapacitet att utföra kraven.
ResourceRequirement	EntityReference	Resurskraven för vilka tidsluckor hämtas.
Potentiella	Boolean	Ett booleskt värde som anger om tidsluckan har potential att uppfylla det begärda kravet.
IsDuplicate	Boolean	Ett booleskt värde som anger om en tidslucka är en dubblett.
AllowOverlapping	Boolean	Ett boooleskt värde som anger om överlappning är tillåten.
Resource	Enhet	Resursen som tidsluckan tillhör. Se resurs för tidslucka för mer information.
Location	Enhet	Platsen har tre attribut: Plats (Entitet): Den har två attribut - Latitud Longitud WorkLocation (Heltal): Den har tre attribut - På plats. Krav på plats utesluter resurstyperna för pooler och lokaler från resultatet. Lokal Platsberoende LocationSourceSlot (Heltal): Platsinformationens källa har tre attribut - Vanligt Anpassad GPS entitet Mobilgranskning
Resa	Enhet	Entiteten innehåller information om restid och distansinformation för en tidslucka. Följande attribut: Sträcka (Dubbel): Resavstånd TravelTime (Dubbel): Restiden i minuter. DistanceFromStartLocation (Dubbel): Sträckan från resursens startplats. DistanceFromEndLocation (Dubbel): Sträckan från resursens slutplats. DistanceMethodSourceSlot (Heltal): Källan eller beräkningstypen för avståndsvärdena Mapptjänst Fågelvägen
Nästa	Enhet	Entiteten innehåller information om restiden och sträckan till nästa bokning av tidslucka. NextScheduleLocation (Entitet): Platsen för nästa bokning. Entiteten har två attribut: Latitud Longitud NextScheduleTravelTime (Heltal): Restiden till nästa bokning på några minuter.
Disposition	Enhet	Detaljerad tillgänglighetsinformation för ett tidslucka. Denna entitet används med tidsgrupper. AvailableIntervals (EntityCollection): En samling med tillgängliga intervaller. Varje entitet i den här samlingen innehåller information om ett tidsintervall. StartTime (DateTime): Starttid. ArrivalTime (DateTime): Ankomsttid. EndTime (DateTime): Sluttiden. TimeGroupId (DateTime): Tidsgrupp-ID. TimeGroupDetailStartTime (DateTime): Tidsgruppens starttid. TimeGroupDetailEndTime (DateTime): Tidsgruppens sluttid. TotalAvailableDuration (Double): Den totala tillgängliga varaktigheten i minuter. TotalAvailableTime (Dubbel): Den totala tillgängliga tiden en resurs har på en dag (i minuter).
TimeGroup	Enhet	Information om en tidsgrupp. TimeGroupId (Guid): Tidsgrupp-ID. TimeGroupDetail (EntityReference): En entitetsreferens till tidsgruppsdetaljen. TimeGroupDetailStartTime (DateTime): Tidsgruppens detalj starttid. TimeGroupDetailEndTime (DateTime): Tidsgruppens sluttid.

Tips/Råd

När du skapar bokningar med hjälp av API:et, använd fältet Potential som beskrivs i tabellen. Om du inte använder fältet kan det leda till överlappande eller olämpliga bokningar.

Tidsluckresurs

Name	Type	Description
Resource	EntityReference	En entitetsreferens till den bokningsbara resursen.
ResourceGroup	EntityReference	En entitetsreferens till den bokningsbara resursgruppen.
BusinessUnit	EntityReference	En enhetsreferens till affärsenheten.
OrganizationalUnit	EntityReference	En entitetsreferens till organisationsenheten.
Resurstyp	Heltal	Resurstypen. Se attributet ResourceType på entiteten BookableResource för möjliga värden.
PoolId	GUID	ID för den pool som resursen är medlem i under tiden för tidsluckan.
CrewId	GUID	ID för den besättning som resursen är medlem i under tiden för tidsluckan.
Karaktäristika	EntityCollection	Egenskaper för bokningsbara resurser. Varje entitet i samlingen innehåller entiteter med egenskaper och klassificeringsinformation. Egenskap (EntityReference): En enhetsreferens till egenskapen. RatingId (Guid) Klassificerings-ID för egenskapen. RatingName (Sträng): Klassificeringsnamnet. RatingValue (Heltal): Klassificeringsnamnet.
HasStartLocation	Boolean	Ett booleskt värde som anger om resursen har en startplats.
HasEndLocation	Boolean	Ett booleskt värde som anger om resursen har en slutplats.
E-post	Sträng	Resursens e-postadress.
Telefon	Sträng	Resursens telefonnummer.
ImagePath	Sträng	Sökvägen till resursens bild.
CalendarId	GUID	Resursens kalender-ID.

Exempel

I detta exempel använder du version 3 av schedule assistant API, som stödjer webb-API-anrop, för ett krav med en varaktighet på 60 minuter. Genom att använda attributet settings filtrerar du resultaten. Du överväger två resurstyper för slutresultatet: 1 och 2 (med andra ord, generiska och kontakttyper).

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

Följande exempel visar korrekt användning av enhetssamlingar. I detta fall specificerar MustChooseFromResourcesden .

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

Feedback

Var den här sidan till hjälp?

Last updated on 2026-05-01