API per la ricerca di disponibilità delle risorse

  • Articolo

Le organizzazioni di assistenza sul campo hanno sempre del lavoro in arrivo che deve essere pianificato da un agente del servizio al telefono o direttamente dal cliente tramite il sito Web. La creazione della prenotazione si basa in genere sulle risorse a disposizione dell'azienda e sui requisiti del lavoro.

Quando si utilizza Dynamics 365 Field Service v8.8.43.51 e Pianificazione risorse universale v3.12.46.21 per pianificare il lavoro, può essere usata l'API msdyn_SearchResourceAvailability per recuperare tutte le risorse idonee per il lavoro e consentire una pianificazione efficiente del lavoro. Al momento della stesura di questo articolo, v3 è l'ultima versione di msdyn_SearchResourceAvailability e supporta le chiamate API Web.

Parametri di input

Nome Digita Descrizione Richiesto Valore predefinito
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 Booleano Imposta su Vero per utilizzare la SA 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:
    1. msdyn_fromdate (DateTime): data iniziale del requisito in formato ISO
    2. msdyn_todate (DateTime): data finale del requisito in formato ISO
    3. msdyn_remainingduration (Integer): la durata residua del requisito in minuti
    4. 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. Le impostazioni sono specificate come attributi in un contenitore di entità. Il tipo di entità non ha importanza, è possibile specificare qualsiasi nome logico di entità. Sì -N/D-
    ResourceSpecification Entity L'attributo resourceSpecification è definito come attributi in un contenitore di entità. Il @odata.type per questa entità dovrebbe essere Microsoft.Dynamics.CRM.expando. No Nessuna

    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.

    Nome Digita Descrizione Richiesto Valore predefinito
    ConsiderSlotsWithLessThanRequiredCapacity Booleano 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 Booleano 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 Booleano 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 Booleano 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 False
    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 saranno considerati non disponibili dalle operazioni di pianificazione. No False
    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
    MovePastStartDateToCurrentDate Booleano Imposta su Vero per spostare una data di inizio passata alla data corrente. No Falso
    UseRealTimeResourceLocation Booleano 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 Entity L'ordinamento può essere specificato utilizzando una raccolta di entità. Ogni entità nella raccolta rappresenterà un criterio di ordinamento. Il @odata.type per questa entità dovrebbe essere Microsoft.Dynamics.CRM.expando. Di seguito sono riportati gli attributi che è necessario popolare:
    1. Nome (String): i criteri di ordinamento
    2. SortOrder (Integer): la direzione di ordinamento (0 per crescente e 1 per decrescente)
    		 No Nessuna
    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:
    1. Value (Decimal): il raggio
    2. 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 verranno restituite risorse per i requisiti in loco.
    MaxNumberOfResourcesToEvaluate Intero Questo attributo definisce un limite per il numero di risorse considerate per la richiesta. No Limite di recupero della disponibilità delle risorse dalla definizione dell'entità pianificabile

    Entità di specifica della risorsa

    Nome Digita Descrizione Richiesto Valore predefinito
    ResourceTypes EntityCollection Questo attributo specifica il tipo di risorsa richiesto per il requisito. Può essere specificato utilizzando una raccolta di entità. Ogni entità nella raccolta rappresenterà un tipo di risorsa prenotabile. Il @odata.type per questa entità dovrebbe essere Microsoft.Dynamics.CRM.msdyn_resourceType. Questo è l'attributo richiesto:
    1. 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. L'aggiunta di risorse a questa raccolta di entità garantisce che siano in cima all'elenco delle risorse disponibili. Anche le risorse che non fanno parte della raccolta di entità saranno nell'elenco, ma solo dopo le risorse preferite. No Nessuna
    RestrictedResources EntityCollection Questo attributo specifica le risorse che non devono essere considerate per il requisito. Tutte le fasce orarie di questa risorsa verranno escluse dall'elenco dei risultati di questa API. No Nessuna
    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 Nessuna
    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

    Gli attribuiti delle risorse Preferred/ Restricted / MustChooseFrom possono essere specificati utilizzando una raccolta di entità di entità di risorse prenotabili. Ogni entità nella raccolta rappresenterà una risorsa Preferred / Restricted / MustChooseFrom. Questo è l'attributo richiesto per loro:

    1. Value (Guid): l'ID della risorsa prenotabile della risorsa Preferred / Restricted / MustChooseFrom. Il @odata.type per questa entità dovrebbe essere Microsoft.Dynamics.CRM.msdyn_bookableresource.

    Vincoli

    Ulteriori vincoli possono essere specificati tramite gli 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:

    Nome Digita Descrizione
    Caratteristiche EntityCollection Una raccolta di ID caratteristica che una risorsa qualificata deve avere.
    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 Booleano 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 Business Unit. 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.

    Nome Digita Descrizione
    TimeSlots EntityCollection Una raccolta dei risultati delle fasce orarie. Per ulteriori informazioni, vedi la sezione (entità fascia oraria)[#time-slots-entity].
    risorse EntityCollection Una raccolta dei risultati delle risorse. Le risorse sono rappresentate come una raccolta di entità con i seguenti attributi:
    1. BookableResource (Entity): l'entità della risorsa prenotabile disponibile per il requisito.
    2. 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.
    1. Timeslots (EntityCollection): fasce orarie delle risorse correlate. La definizione delle fasce orarie è la stessa descritta nella sezione fasce orarie.
    2. 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.
    1. Message (String): messaggio di eccezione
    2. ResourcesTruncatedAt (Integer): se il numero di risorse ha superato il limite di recupero; il numero dove le risorse sono state troncate.

    Entità fasce orarie

    Nome Digita Descrizione
    ID GUID Identificatore univoco della fascia oraria
    Digita Intero Il tipo di fascia oraria può essere uno dei seguenti:
    • 0: disponibile
    • 1: pianificato
    • 2: non disponibile
    • 3: pausa
    StartTime DataOra L'ora di inizio della fascia oraria. Se è previsto un viaggio per il requisito, questa è l'ora di inizio del viaggio. In caso contrario, questa è l'ora di inizio del requisito.
    ArrivalTime DataOra L'ora di arrivo della fascia oraria. Se è previsto un viaggio per il requisito, questa è l'ora di inizio del requisito una volta completato il viaggio. In caso contrario, è uguale all'ora di inizio della fascia oraria.
    EndTime DataOra 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 Booleano Un valore booleano che indica se la fascia oraria ha il potenziale per soddisfare il requisito richiesto.
    IsDuplicate Booleano Un valore booleano che indica se la fascia oraria è un duplicato.
    AllowOverlapping Booleano 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:
    1. Location (Entity): ha due attributi:
      • Latitudine
      • Longitudine
    2. WorkLocation (Integer): ha tre attributi:
      • In loco
      • Struttura
      • Indipendente dalla posizione
    3. 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:
    1. Distance (Double): la distanza del viaggio
    2. TravelTime (Double): la durata del viaggio in minuti.
    3. DistanceFromStartLocation (Double): la distanza dalla posizione iniziale della risorsa.
    4. DistanceFromEndLocation (Double): la distanza dalla posizione finale della risorsa.
    5. DistanceMethodSourceSlot (Integer): l'origine/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.
    1. NextScheduleLocation (Entity): la posizione della prossima prenotazione. L'entità ha due attributi:
      • Latitudine
      • Longitudine
    2. NextScheduleTravelTime (Integer): la durata del viaggio alla prossima prenotazione in minuti.
    Disponibilità Entity Le informazioni dettagliate sulla disponibilità per una fascia oraria. Viene utilizzato in connessione con i gruppi di ore.
    1. 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.
    2. TotalAvailableDuration (Double): la durata totale disponibile in minuti.
    3. TotalAvailableTime (Double): il tempo totale disponibile che una risorsa ha in un giorno (in minuti).
    TimeGroup Entity I dettagli su un gruppo di ore.
    1. TimeGroupId (Guid): l'ID del gruppo di ore.
    2. TimeGroupDetail (EntityReference): un riferimento di entità al dettaglio del gruppo di ore.
    3. TimeGroupDetailStartTime (DateTime): l'ora di inizio del dettaglio del gruppo di ore.
    4. TimeGroupDetailEndTime (DateTime): l'ora di fine del dettaglio del gruppo di ore.

    Suggerimento

    Quando crei prenotazioni con l'API, utilizza 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.
    1. Characteristic (EntityReference): un riferimento di entità alla caratteristica.
    2. RatingId (Guid): l'ID valutazione per la caratteristica.
    3. RatingName (String): il nome della valutazione.
    4. RatingValue (Integer): il valore della valutazione.
    HasStartLocation Booleano Un valore booleano che indica se la risorsa ha una posizione iniziale.
    HasEndLocation Booleano 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, la v3 dell'API dell'assistente di pianificazione che consente chiamate API Web viene utilizzata per un requisito della durata di 60 minuti. Utilizzando l'attributo impostazioni, i risultati vengono filtrati. Per i risultati finali vengono presi in considerazione due tipi di risorse: 1 e 2 (in altre parole, generico e contatto).

    {
    "Version": "3",
    "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"
                    }
                }
            ],
            "Territories@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
            "Territories": [
                {
                    "@odata.type": "Microsoft.Dynamics.CRM.expando",
                    "value": "cc19f004-4483-ee11-8178-000d3a5c32c3"
                }
            ]

    L'esempio seguente dimostra l'utilizzo corretto delle raccolte di entità. In questo caso, specifica MustChooseFromResources.

    {
    "Version": "3",
    "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"
            }
        ],
        "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"
                    }
                }
            ],
            "Territories@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
            "Territories": [
                {
                    "@odata.type": "Microsoft.Dynamics.CRM.expando",
                    "value": "cc19f004-4483-ee11-8178-000d3a5c32c3"
                }
            ]
        }
    }
}
        }
    }
}