API per la ricerca di disponibilità delle risorse

Le organizzazioni di Field Service devono pianificare il lavoro, spesso tramite un agente di servizio direttamente dal cliente. Le prenotazioni sono generalmente create sulla base delle risorse a disposizione dell'azienda e sui requisiti del lavoro.

Quando usi almeno Dynamics 365 Customer Voice v8.8.43.51 e Universal Resource Scheduling v3.12.46.21 per programmare il lavoro, usa l'API msdyn_SearchResourceAvailability per recuperare tutte le risorse idonee al lavoro, così da poter programmare il lavoro in modo efficiente. Al momento della stesura, v3 è l'ultima versione e msdyn_SearchResourceAvailability supporta le chiamate web API.

Nota

Usa l'ultima versione dell'API poiché le versioni più vecchie potrebbero utilizzare metodi di autenticazione obsoleti.

Parametri di input

Name	Type	Descrzione	Obbligatorio	Default
Versione	Stringa	Il numero di versione dell'API identifica la versione dell'API da richiamare. Segue il formato "principale.secondaria.patch". La richiesta non deve contenere il numero di versione completo. Se viene specificata solo una versione principale, verrà richiamata la versione secondaria e patch più alta disponibile per quella versione principale. Se vengono specificate sia la versione principale che quella secondaria, verrà richiamata la versione patch più alta disponibile. Se vengono menzionate tutte e tre le parti della versione, verrà richiamata la versione esatta dell'API specificata.	Sì	-N/D-
IsWebApi	Boolean	Imposta su True per usare l'assistente di calendario tramite l'API web.	Sì	-N/D-
Requisito	Entity	Questo attributo specifica il requisito della risorsa per cui viene recuperata la disponibilità della risorsa. Dovrebbe essere un'entità di tipo msdyn_resourcerequirement. Il requisito può essere un record preesistente dal database oppure uno creato al volo con i vincoli necessari. L'entità dovrebbe contenere tutte le specifiche rilevanti per la ricerca. Il `@odata.type` per questa entità dovrebbe essere `Microsoft.Dynamics.CRM.msdyn_requirement`. Di seguito sono riportati alcuni attributi importanti da popolare: msdyn_fromdate (DateTime): data iniziale del requisito in formato ISO msdyn_todate (DateTime): data finale del requisito in formato ISO msdyn_remainingduration (Integer): la durata residua del requisito in minuti msdyn_duration (Integer): la durata totale del requisito in minuti	Sì	-N/D-
Impostazioni	Entity	L'attributo impostazioni aiuta a filtrare ulteriormente le risorse recuperate. Specifica le impostazioni come attributi in una entity bag. Il tipo di entità non ha importanza. È possibile specificare qualsiasi nome logico di entità.	Sì	-N/D-
ResourceSpecification	Entity	Definisci l'attributo `resourceSpecification` come attributi in una borsa di entità. Il `@odata.type` per questa entità dovrebbe essere `Microsoft.Dynamics.CRM.expando`.	No	None

Entità impostazioni

L'entità impostazioni non è un'entità che esiste in Dataverse; tuttavia, è una raccolta di tutti i seguenti attributi che aiuta l'API dell'assistente di pianificazione a filtrare i risultati. Pertanto, il @odata.type per questa entità dovrebbe essere Microsoft.Dynamics.CRM.expando.

Name	Type	Descrzione	Obbligatorio	Default
ConsiderSlotsWithLessThanRequiredCapacity	Boolean	Imposta su Vero se una fascia oraria con capacità inferiore a quella richiesta (sforzo) deve essere considerata nel calcolo delle potenziali fasce orarie disponibili sul calendario della risorsa.	No	Falso
ConsiderSlotsWithLessThanRequiredDuration	Boolean	Imposta su Vero se una fascia oraria con durata inferiore a quella richiesta deve essere considerata nel calcolo delle potenziali fasce orarie disponibili sul calendario della risorsa.	No	Falso
ConsiderSlotsWithOverlappingBooking	Boolean	Imposta su Vero se una fascia oraria con prenotazioni sovrapposte deve essere considerata nel calcolo delle potenziali fasce orarie disponibili sul calendario della risorsa.	No	Falso
ConsiderSlotsWithProposedBookings	Boolean	Imposta su Vero se una fascia oraria con prenotazioni proposte deve essere considerata nel calcolo delle potenziali fasce orarie disponibili sul calendario della risorsa.	No	Falso
ConsiderAppointments	Boolean	Impostalo su Vero per l'API di disponibilità delle risorse di ricerca per rispettare gli appuntamenti Dataverse come prenotazioni della risorsa, purché siano state impostate le impostazioni a livello di organizzazione e risorse. Gli appuntamenti con stato Occupato o Completato sono considerati non disponibili per le operazioni di programmazione.	No	Falso
ConsiderTravelTime	Boolean	Imposta su Vero se la durata del viaggio deve essere considerata quando si calcolano le potenziali fasce orarie sul calendario della risorsa.	No	Vero
ExcludeResourceCharacteristics	Boolean	Imposta questo su True per escludere le caratteristiche delle risorse per gli slot orari in risposta.	No	Falso
MovePastStartDateToCurrentDate	Boolean	Imposta su Vero per spostare una data di inizio passata alla data corrente.	No	Falso
UseRealTimeResourceLocation	Boolean	Imposta su Vero se la posizione in tempo reale delle risorse deve essere usata quando si calcolano le potenziali fasce orarie sul calendario della risorsa.	No	Falso
SortOrder	EntityCollection	Specificare l'ordinamento utilizzando un insieme di entità. Ogni entità nell'insieme rappresenta un criterio di ordinamento e può ordinare `Resources` solo in base alla risposta, ma non `TimeSlots`. Il `@odata.type` per questa entità dovrebbe essere `Microsoft.Dynamics.CRM.expando`. Di seguito sono riportati gli attributi che è necessario popolare: Name (String): i criteri di ordinamento SortOrder (Integer): la direzione di ordinamento (0 per crescente e 1 per decrescente)	No	None
MaxResourceTravelRadius	Entity	Questo attributo specifica il raggio di viaggio massimo che può essere definito in un'entità. Il `@odata.type` per questa entità dovrebbe essere `Microsoft.Dynamics.CRM.expando`. Di seguito sono riportati gli attributi che è necessario popolare: Value (Decimal): il raggio Unit (Integer): l'unità della distanza. Vedi il set di opzioni dell'unità msdyn_distance per i possibili valori.	No	0 km. In tal caso, non viene restituita alcuna risorsa per i requisiti in loco.
MaxNumberOfResourcesToEvaluate	Intero	Questo attributo definisce un limite per il numero di risorse considerate per la richiesta.	No	Se questo attributo non è incluso nella chiamata API, il sistema utilizza il Limite di Recupero della Disponibilità delle Risorse dalla definizione di entità schedulabile come definito nelle impostazioni di modifica per entità abilitate. Se incluso nella chiamata, sovrascrive il limite di recupero della disponibilità delle risorse definito.
ConsiderOutlookSchedules	Boolean	Imposta questo su True se bisogna considerare gli schedule da Outlook. Disponibile solo nelle versioni 3.1.0 e successive.	No	Falso

Entità di specifica della risorsa

Name	Type	Descrzione	Obbligatorio	Default
ResourceTypes	EntityCollection	Questo attributo specifica il tipo di risorsa richiesto per il requisito. Usa una collezione di entità per specificare questo attributo. Ogni entità nella raccolta rappresenterà un tipo di risorsa prenotabile. Il `@odata.type` per questa entità dovrebbe essere `Microsoft.Dynamics.CRM.msdyn_resourceType`. Questo attributo è richiesto: Value (Integer): il valore del set di opzioni che rappresenta il tipo di risorsa: 1- Generico 2- Contatto 3- Utente 4- Attrezzature 5- Account 6- Team 7- Struttura 8- Pool	No	Tutti i tipi di risorse eccetto i team
PreferredResources	EntityCollection	Questo attributo specifica le risorse preferite per il requisito. Aggiungi risorse a questa collezione di entità per assicurarti che siano in cima alla lista delle risorse disponibili. Anche le risorse che non fanno parte della collezione di entità sono nella lista, ma solo dopo le risorse preferite.	No	None
RestrictedResources	EntityCollection	Questo attributo specifica le risorse che non devono essere considerate per il requisito. Tutti gli slot temporali di questa risorsa vengono filtrati dall'elenco dei risultati di questa API.	No	None
MustChooseFromResources	EntityCollection	Questo attributo specifica le uniche risorse che possono essere presenti nell'elenco delle risorse disponibili. Filtrerà tutti gli altri risultati eliminandoli dall'elenco di output.
Vincoli	Entity	Questo attributo specifica i vincoli aggiuntivi che dovrebbero essere applicati al recupero delle risorse disponibili.	No	None
RetrieveResourcesQueryId	GUID	L'ID per la query Recupera risorse.	No	L'ID della query Recupera risorse predefinita.
BookedResourceId	GUID	Questo attributo specifica la risorsa attualmente prenotata per il requisito.	No	None

Nota

Usa una collezione di entità di risorse prenotabili per specificare gli attributi risorse Preferita, Limitata e MustChooseFrom . Ogni entità nella collezione rappresenta una risorsa Preferittiva, Ristretta o MustChooseFrom . Questo attributo è richiesto per loro:

Valore (Guid): L'ID risorsa prenotabile della risorsa Preferita, Ristretta o MustChooseFrom . Il @odata.type per questa entità dovrebbe essere Microsoft.Dynamics.CRM.msdyn_bookableresource.

Vincoli

Specificare vincoli aggiuntivi tramite attributi in questa entità. Il tipo di entità non ha importanza. È possibile specificare qualsiasi nome logico di entità.

Esamina la query Recupera risorse nelle impostazioni della scheda di pianificazione per individuare i vincoli che potrebbero essere applicati. Per impostazione predefinita, sono inclusi i seguenti:

Name	Type	Descrzione
Caratteristiche	EntityCollection	Un insieme di caratteristiche che una risorsa qualificata deve possedere. Ogni voce contiene un `characteristic` con l'ID caratteristico. Opzionalmente, includere un `ratingvalue` con l'ID del valore di valutazione per filtrare le risorse in base a un livello di competenza specifico.
Ruoli	EntityCollection	Una raccolta di ID ruolo che una risorsa qualificata deve avere.
Aree	EntityCollection	Una raccolta di ID area. Una risorsa qualificata deve essere assegnata a una delle aree.
UnspecifiedTerritory	Boolean	In combinazione con il vincolo delle aree, specifica che una risorsa qualificata deve essere assegnata a una delle aree o a nessuna area.
OrganizationalUnits	EntityCollection	Una raccolta di ID unità organizzativa. Una risorsa qualificata deve essere membro di una delle unità organizzative specificate.
Teams	EntityCollection	Una raccolta di ID team. Una risorsa qualificata deve appartenere a uno dei team (implica che il tipo di risorsa è un utente di sistema).
BusinessUnits	EntityCollection	Una raccolta di ID di unità aziendali. Una risorsa qualificata deve appartenere a una delle Business Unit (implica che la risorsa è un utente di sistema).

Parametri di output

Al livello più alto, l'output ha i seguenti quattro parametri. I risultati sono rappresentati in raccolte di entità ed entità. Le risposte potrebbero non includere tutti gli attributi descritti qui poiché i valori null o valori non ND vengono omessi dalla risposta. Verifica sempre la presenza di un attributo prima di provare ad accedervi.

Name	Type	Descrzione
TimeSlots	EntityCollection	Una raccolta dei risultati delle fasce orarie. Per altre informazioni, vedere la sezione Entità fascia oraria .
risorse	EntityCollection	Una raccolta dei risultati delle risorse. Le risorse sono rappresentate come una raccolta di entità con i seguenti attributi: BookableResource (Entity): l'entità della risorsa prenotabile disponibile per il requisito. TotalAvailableTime (Double): il tempo totale disponibile per la risorsa per eseguire il requisito.
Elementi correlati	Entity	Le risorse correlate rappresentano risorse e fasce orarie di risorse che non sono direttamente qualificate per il requisito richiesto ma sono correlate. Ad esempio, se un membro del team si qualifica per un requisito, gli altri membri di quel team sono risultati correlati. Timeslots (EntityCollection): fasce orarie delle risorse correlate. La definizione delle fasce orarie è la stessa descritta nella sezione fasce orarie. Resources (EntityCollection): le risorse correlate. La definizione delle risorse è la stessa descritta nella definizione degli attributi delle risorse.
Eccezioni	Entity	Questo attributo contiene informazioni su tutte le eccezioni che si sono verificate e informazioni su se e dove la ricerca delle risorse è stata troncata. Message (String): messaggio di eccezione ResourcesTruncatedAt (Integer): se il numero di risorse ha superato il limite di recupero; il numero dove le risorse sono state troncate.

Entità fasce orarie

Name	Type	Descrzione
ID	GUID	Identificatore univoco della fascia oraria
Type	Intero	Il tipo di fascia oraria. Può essere uno dei valori seguenti: 0: disponibile 1: pianificato 2: non disponibile 3: pausa
StartTime	Data/Ora	L'ora di inizio della fascia oraria. Se ci sono viaggi per il requisito, questo è l'orario di inizio del viaggio. Altrimenti, questo è l'orario di inizio del requisito.
ArrivalTime	Data/Ora	L'ora di arrivo della fascia oraria. Se ci sono viaggi per il requisito, questo è l'orario di inizio del requisito, dopo il completamento del viaggio. In caso contrario, è uguale all'ora di inizio della fascia oraria.
EndTime	Data/Ora	L'ora di fine della fascia oraria.
Lavoro	Intero	Lo sforzo o la capacità della risorsa di soddisfare i requisiti.
ResourceRequirement	EntityReference	Il requisito di risorsa per cui vengono recuperate le fasce orarie.
Potential	Boolean	Un valore booleano che indica se la fascia oraria ha il potenziale per soddisfare il requisito richiesto.
IsDuplicate	Boolean	Un valore booleano che indica se la fascia oraria è un duplicato.
AllowOverlapping	Boolean	Un valore booleano che indica se la sovrapposizione è consentita.
Risorsa	Entity	La risorsa a cui appartiene la fascia oraria. Per ulteriori informazioni, vedi risorsa fascia oraria.
Location	Entity	La posizione ha tre attributi: Location (Entity): ha due attributi: Latitudine Longitudine WorkLocation (Integer): ha tre attributi: In loco. I requisiti in loco escludono i tipi di risorse del pool e della struttura dai risultati. Struttura Indipendente dalla posizione LocationSourceSlot (Integer): l'origine delle informazioni sulla posizione ha tre attributi: Elementi comuni Entità GPS personalizzata Controllo per dispositivi mobili
Viaggi	Entity	Questa entità contiene i dettagli delle informazioni sulla distanza e durata del viaggio per una fascia oraria. Gli attributi sono i seguenti: Distance (Double): la distanza del viaggio TravelTime (Double): la durata del viaggio in minuti. DistanceFromStartLocation (Double): la distanza dalla posizione iniziale della risorsa. DistanceFromEndLocation (Double): la distanza dalla posizione finale della risorsa. DistanceMethodSourceSlot (Intero): La sorgente o il tipo di calcolo dei valori della distanza Servizio mappe In linea d'aria
Successiva	Entity	Questa entità contiene i dettagli sulla distanza e la durata del viaggio alla prenotazione della fascia oraria successiva. NextScheduleLocation (Entity): la posizione della prossima prenotazione. L'entità ha due attributi: Latitudine Longitudine NextScheduleTravelTime (Integer): la durata del viaggio alla prossima prenotazione in minuti.
Disponibilità	Entity	Le informazioni dettagliate sulla disponibilità per una fascia oraria. Questa entità viene usata con i gruppi temporali. AvailableIntervals (EntityCollection): una raccolta di intervalli disponibili. Ogni entità in questa raccolta contiene dettagli su un intervallo di gruppi di ore. StartTime (DateTime): l'ora di inizio. ArrivalTime (DateTime): l'ora di arrivo. EndTime (DateTime): l'ora di fine. TimeGroupId (DateTime): l'ID del gruppo di ore. TimeGroupDetailStartTime (DateTime): l'ora di inizio del gruppo di ore. TimeGroupDetailEndTime (DateTime): l'ora di fine del gruppo di ore. TotalAvailableDuration (Double): la durata totale disponibile in minuti. TotalAvailableTime (Double): il tempo totale disponibile che una risorsa ha in un giorno (in minuti).
TimeGroup	Entity	I dettagli su un gruppo di ore. TimeGroupId (Guid): l'ID del gruppo di ore. TimeGroupDetail (EntityReference): un riferimento di entità al dettaglio del gruppo di ore. TimeGroupDetailStartTime (DateTime): l'ora di inizio del dettaglio del gruppo di ore. TimeGroupDetailEndTime (DateTime): l'ora di fine del dettaglio del gruppo di ore.

Suggerimento

Quando crei prenotazioni usando l'API, usa il campo Potenziale descritto nella tabella. Il mancato utilizzo di tale campo potrebbe comportare prenotazioni sovrapposte o non idonee.

Risorsa fascia oraria

Name	Type	Descrzione
Risorsa	EntityReference	Un riferimento entità per la risorsa prenotabile.
ResourceGroup	EntityReference	Un riferimento entità per il gruppo di risorse prenotabili.
BusinessUnit	EntityReference	Un riferimento di entità alla Business Unit.
OrganizationalUnit	EntityReference	Un riferimento entità per l'unità organizzativa.
ResourceType	Intero	Tipo di risorsa. Vedi l'attributo ResourceType nell'entità BookableResource per i possibili valori.
PoolId	GUID	L'ID del pool di cui fa parte la risorsa per la durata dalla fascia oraria.
CrewId	GUID	L'ID del team di cui fa parte la risorsa per la durata dalla fascia oraria.
Caratteristiche	EntityCollection	Le caratteristiche delle risorse prenotabili. Ciascuna entità nella raccolta contiene entità con caratteristiche e informazioni sulla valutazione. Characteristic (EntityReference): un riferimento di entità alla caratteristica. RatingId (Guid): l'ID valutazione per la caratteristica. RatingName (String): il nome della valutazione. RatingValue (Integer): il valore della valutazione.
HasStartLocation	Boolean	Un valore booleano che indica se la risorsa ha una posizione iniziale.
HasEndLocation	Boolean	Un valore booleano che indica se la risorsa ha una posizione finale.
Indirizzo e-mail	Stringa	L'indirizzo e-mail della risorsa.
Telefono	Stringa	Il numero di telefono della risorsa.
ImagePath	Stringa	Il percorso dell'immagine della risorsa.
CalendarId	GUID	L'ID calendario della risorsa.

Esempi

In questo esempio, si utilizza la versione 3 dell'API dell'assistente di programmazione, che supporta chiamate web API, per un requisito della durata di 60 minuti. Usando l'attributo settings , filtri i risultati. Per i risultati finali consideri due tipi di risorse: 1 e 2 (in altre parole, generica e contatto).

{
    "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'esempio seguente dimostra l'utilizzo corretto delle raccolte di entità. In questo caso, specifica 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"
                }
            ]
        }
    }
}

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-04-07