Nuta
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować się zalogować lub zmienić katalog.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Organizacje świadczące usługi terenowe muszą planować pracę, często za pośrednictwem usługi agent bezpośrednio przez klienta. Rezerwacje są zazwyczaj tworzone w oparciu o zasoby dostępne dla firmy i wymagania dotyczące pracy.
W przypadku korzystania co najmniej z Dynamics 365 Field Service v8.8.43.51 i Universal Resource Scheduling v3.12.46.21 do planowania pracy, interfejs API msdyn_SearchResourceAvailability może być używany do pobierania wszystkich kwalifikujących się zasobów dla zadania, aby umożliwić wydajne planowanie pracy. W czasie pisania wersja v3 jest najnowszą wersją msdyn_SearchResourceAvailability i obsługuje wywołania interfejsów API sieci web.
Notatka
Korzystanie z najnowszej wersji API jest wysoce zalecane, ponieważ starsze wersje mogą używać przestarzałych metod uwierzytelniania.
Parametry wejściowe
| Nazwa/nazwisko | Typ | Podpis | Wymagania | Wartość domyślna |
|---|---|---|---|---|
| Wersja | String | Numer wersji interfejsu API identyfikuje wersję interfejsu API, która powinna być wywoływana. Jest to zgodne z formatem major.minor.patch: Żądanie nie musi zawierać pełnego numeru wersji.
|
Tak | Nie dotyczy |
| IsWebApi | logiczny | Ustaw wartość na True, aby używać asystenta planowania za pośrednictwem interfejsu API sieci web. | Tak | Nie dotyczy |
| Wymaganie | Jednostka | Ten atrybut określa wymaganie zasobu, dla którego są pobierane dostępne zasoby. Ma to być encja typu msdyn_resourcerequirement. Wymaganie może być wstępnie istniejącym rekordem z bazy danych lub utworzonym na bieżąco z niezbędnymi ograniczeniami. Encja powinna zawierać wszystkie informacje szczegółowe związane z wyszukiwaniem.
@odata.type dla tej encji powinno być Microsoft.Dynamics.CRM.msdyn_requirement. Oto kilka ważnych atrybutów do wypełnienia:
|
Tak | Nie dotyczy |
| Ustawienia | Jednostka | Atrybut ustawienia ułatwia dalsze filtrowanie pobranych zasobów. Ustawienia są określone jako atrybuty w torbie encji. Typ encji nie ma znaczenia. Można określić dowolną nazwę logiczną encji. | Tak | Nie dotyczy |
| ResourceSpecification | Jednostka | Atrybut resourceSpecification jest definiowany jako atrybut w torbie encji.
@odata.type dla tej encji powinno być Microsoft.Dynamics.CRM.expando. |
Nie. | None |
Encja Ustawienia
Encja ustawień nie jest encją, która istnieje w Dataverse, ale jest to kolekcja wszystkich następujących atrybutów, które pomagają interfejsowi API asystenta planowania w filtrowaniu wyników. I dlatego @odata.type dla tej encji powinno być Microsoft.Dynamics.CRM.expando.
| Nazwa/nazwisko | Typ | Podpis | Wymagania | Wartość domyślna |
|---|---|---|---|---|
| ConsiderSlotsWithLessThanRequiredCapacity | logiczny | Ustaw na True jeśli slot czasu o mniejszej niż wymagana wydajności (nakład pracy) powinien być rozważany podczas obliczania potencjalnych dostępnych przedziałów czasu w kalendarzu zasobu. | Nie. | Fałsz |
| ConsiderSlotsWithLessThanRequiredDuration | logiczny | Ustaw na True jeśli slot czasu o mniejszym niż wymagany czasie trwania powinien być rozważany podczas obliczania potencjalnych dostępnych przedziałów czasu w kalendarzu zasobu. | Nie. | Fałsz |
| ConsiderSlotsWithOverlappingBooking | logiczny | Ustaw na True jeśli slot czasu o nakładających się rezerwacjach powinien być rozważany podczas obliczania potencjalnych dostępnych przedziałów czasu w kalendarzu zasobu. | Nie. | Fałsz |
| ConsiderSlotsWithProposedBookings | logiczny | Ustaw na True jeśli slot czasu o proponowanych rezerwacjach powinien być rozważany podczas obliczania potencjalnych dostępnych przedziałów czasu w kalendarzu zasobu. | Nie. | Fałsz |
| ConsiderAppointments | logiczny | Ustaw na True dla interfejsu API wyszukiwania dostępności zasobu, aby uznać istniejące terminy Dataverse jako rezerwacje zasobu, zakładając, że ustawiono ustawienia organizacji i na poziomie zasobów. Terminy ze stanami Zajęty lub Zakończony będą uważane za niedostępne dla operacji planowania. | Nie. | Fałsz |
| ConsiderTravelTime | logiczny | Ustaw na True jeśli podczas obliczania potencjalnych przedziałów czasu w kalendarzu zasobu należy uwzględnić czas podróży. | Nie. | Prawda |
| MovePastStartDateToCurrentDate | logiczny | Ustaw na True aby przenieść datę rozpoczęcia z przeszłości. | Nie. | Fałsz |
| UseRealTimeResourceLocation | logiczny | Ustaw na True jeśli podczas obliczania potencjalnych przedziałów czasu w kalendarzu zasobu należy użyć lokalizacji zasobów w czasie rzeczywistym. | Nie. | Fałsz |
| SortOrder | EntityCollection | Określ porządek sortowania przy użyciu kolekcji jednostek. Każda jednostka w kolekcji reprezentuje jedno kryterium sortowania i może sortować Resources tylko na podstawie odpowiedzi, ale nie TimeSlots.
@odata.type dla tej encji powinno być Microsoft.Dynamics.CRM.expando. Należy wypełnić następujące atrybuty:
|
Nie. | None |
| MaxResourceTravelRadius | Jednostka | Ten atrybut określa maksymalną wartość, jaką można zdefiniować dla encji.
@odata.type dla tej encji powinno być Microsoft.Dynamics.CRM.expando. Należy wypełnić następujące atrybuty:
|
Nie. | 0 km. W takim przypadku nie są zwracane żadne zasoby dla wymagań na miejscu. |
| MaxNumberOfResourcesToEvaluate | Integer | Ten atrybut definiuje ograniczenie liczby zasobów rozważanych dla żądania. | Nie. | Jeśli ten atrybut nie jest uwzględniony w wywołaniu interfejsu API, system używa limitu pobierania dostępności zasobów z definicji encji, którą można zaplanować, zgodnie z definicją w obszarze Edytowanie ustawień dla włączonych encji. Jeśli zostanie uwzględniony w wywołaniu, zastąpi zdefiniowany limit pobierania dostępności zasobów. |
| Rozważ harmonogramy programu Outlook | logiczny | Ustaw tę wartość na True, jeśli mają być uwzględniane harmonogramy z programu Outlook. Dostępne tylko w wersjach 3.1.0 i nowszych | Nie. | Fałsz |
Encja Specyfikacja zasobu
| Nazwa/nazwisko | Typ | Podpis | Wymagania | Wartość domyślna |
|---|---|---|---|---|
| ResourceTypes | EntityCollection | Ten atrybut określa typ zasobu wymaganego dla wymagania. Można go określić przy użyciu kolekcji encji. Każda encja w kolekcji reprezentuje jeden typ zasobu, który można zarezerwować.
@odata.type dla tej encji powinno być Microsoft.Dynamics.CRM.msdyn_resourceType. Oto wymagany atrybut:
|
Nie. | Wszystkie typy zasobów z wyjątkiem personelu |
| PreferredResources | EntityCollection | Ten atrybut określa zasoby preferowane dla wymagania. Dodanie zasobów do tej kolekcji encji gwarantuje, że znajdują się na początku listy dostępnych zasobów. Nawet zasoby, które nie są częścią kolekcji encji, znajdują się na liście, ale tylko po preferowanych zasobach. | Nie. | None |
| RestrictedResources | EntityCollection | Ten atrybut określa zasoby jakie należy rozważyć dla wymagania. Wszystkie przydziały czasu tego zasobu będą filtrowane poza listą wyników z tego interfejsu API. | Nie. | None |
| MustChooseFromResources | EntityCollection | Ten atrybut określa jedyne zasoby, które mogą znaleźć się na liście dostępnych zasobów. Odfiltrowuje pozostałe wyniki z listy danych wyjściowych. | ||
| Ograniczenia | Jednostka | Ten atrybut określa dodatkowe ograniczenia, które należy zastosować do pobierania dostępnych zasobów. | Nie. | None |
| RetrieveResourcesQueryId | Identyfikator GUID | Identyfikator zapytania Pobieranie zasobów. | Nie. | Domyślny identyfikator zapytania Pobieranie zasobu. |
| BookedResourceId | Identyfikator GUID | Ten atrybut określa zasób aktualnie zarezerwowany dla wymagania. | Nie. | None |
Notatka
Atrybuty zasobów Preferowane/ Zastrzeżone / MustChooseFrom można określić korzystając z kolekcji encji, które można zarezerwować. Każda encja w kolekcji reprezentuje jeden zasób preferowany / ograniczony / MustChooseFrom. Oto wymagany dla nich atrybut:
-
Wartość (Guid): Identyfikator zasobu z możliwością rezerwacji dla zasobu Preferowane / Zastrzeżone / MustChooseFrom.
@odata.typedla tej encji powinno byćMicrosoft.Dynamics.CRM.msdyn_bookableresource.
Ograniczenia
Dodatkowe ograniczenia można określić za pomocą atrybutów w tej encji. Typ encji nie ma znaczenia. Można określić dowolną nazwę logiczną encji.
Przejrzyj Zapytanie dotyczące zasobów w ustawieniach tablicy harmonogramu, aby określić, które ograniczenia mogą mieć zastosowanie. Domyślnie zawiera on następujące elementy:
| Nazwa/nazwisko | Typ | Podpis |
|---|---|---|
| Charakterystyki | EntityCollection | Zbiór charakterystyk identyfikatorów, które musi mieć kwalifikowany zasób. |
| Role | EntityCollection | Zbiór identyfikatorów ról, które musi mieć kwalifikowany zasób. |
| Obszary | EntityCollection | Zbiór identyfikatorów obszarów. Kwalifikowany zasób musi być przypisany do jednego z obszarów. |
| UnspecifiedTerritory | logiczny | W połączeniu z ograniczeniem obszarów określa, że zakwalifikowany musi być przypisany do jednego z obszarów lub nie musi mieć przypisanego obszaru. |
| OrganizationalUnits | EntityCollection | Kolekcja identyfikatorów jednostek organizacyjnych. Kwalifikowany zasób musi być członkiem jednej z określonych jednostek organizacyjnych. |
| Teams | EntityCollection | Zbiór identyfikatorów zespołu. Kwalifikowany zasób musi należeć do jednego z zespołów (oznacza, że typ zasobu jest użytkownikiem systemowym). |
| BusinessUnits | EntityCollection | Kolekcja identyfikatorów jednostki biznesowej. Kwalifikowany zasób musi należeć do jednej z jednostek biznesowych (oznacza, że zasób jest użytkownikiem systemowym). |
Parametry wyjściowe
Na najwyższym poziomie parametr wyjściowy ma następujące cztery parametry. Wyniki są reprezentowane w kolekcjach encji i encjach. Odpowiedzi mogą nie zawierać wszystkich atrybutów opisanych tutaj jako wartość null lub wartości Nie dotyczy są pominięte w odpowiedzi. Przed próbą uzyskania dostępu do atrybutu zawsze należy sprawdzić jego obecność.
| Nazwa/nazwisko | Typ | Podpis |
|---|---|---|
| TimeSlots | EntityCollection | Kolekcja wyników przedziałów czasu. Aby uzyskać więcej informacji, zobacz sekcję encji przedziału czasu . |
| Zasoby | EntityCollection | Kolekcja wyników zasobów. Zasoby są reprezentowane jako kolekcja encji o następujących atrybutach:
|
| Pokrewne | Jednostka | Zasoby pokrewne reprezentują zasoby i przedziały czasu zasobów, które nie są bezpośrednio zakwalifikowane do żądanego wymagania, ale są powiązane. Jeśli na przykład członek zespołu zostanie zakwalifikowany do wymagania, inni członkowie tego personelu będą wynikami pokrewnymi.
|
| Wyjątki | Jednostka | Ten atrybut zawiera informacje o wszystkich wyjątkach, jakie wystąpiły, oraz informacje o tym, czy i gdzie zostało obcięte wyszukiwanie zasobów.
|
Encja Przedziały czasu
| Nazwa/nazwisko | Typ | Podpis |
|---|---|---|
| identyfikator | Identyfikator GUID | Unikatowy identyfikator dla przedziału czasu |
| Typ | Integer | Oto możliwe typy przedziałów czasu:
|
| StartTime | DateTime | Godzina rozpoczęcia przedziału czasu. Jeśli jest podróż dla wymagania, jest to czas rozpoczęcia podróży. Jeśli nie, to czas rozpoczęcia wymagania. |
| ArrivalTime | DateTime | Godzina przybycia dla przedziału czasu. Jeśli jest podróż dla wymagania, jest to czas rozpoczęcia wymagania, po zakończeniu podróży. Jeśli nie, jest to ta sama godzina co godzina rozpoczęcia przedziału czasu. |
| EndTime | DateTime | Godzina zakończenia przedziału czasu. |
| Nakład pracy | Integer | Nakład pracy lub wydajność zasobu związane z wykonywaniem wymagań. |
| ResourceRequirement | EntityReference | Wymaganie zasobu, dla którego są pobierane przedziały czasu. |
| Potencjalny | logiczny | Wartość logiczna wskazująca, czy przedział czasu ma szansę spełnić żądane wymaganie. |
| IsDuplicate | logiczny | Wartość logiczna wskazująca, czy dany przedział czasu jest duplikatem. |
| AllowOverlapping | logiczny | Wartość logiczna wskazująca, czy dozwolone jest nakładanie się. |
| Zasób | Jednostka | Zasób, do którego należy przedział czasu. Aby uzyskać więcej informacji, zobacz zasoby dotyczące przedziałów czasowych. |
| Lokalizacja | Jednostka | Lokalizacja ma trzy atrybuty:
|
| Podróż | Jednostka | Ta encja zawiera szczegółowe informacje o czasie podróży i odległości dla przedziału czasu. Oto atrybuty:
|
| Następne | Jednostka | Ta encja zawiera szczegółowe informacje o czasie podróży i odległości do następnej rezerwacji przedziału czasu.
|
| Dostępność | Jednostka | Szczegółowe informacje o dostępności dla przedziału czasu. Jest to używane z grupami czasowymi.
|
| TimeGroup | Jednostka | Szczegółowe informacje o grupie czasowej.
|
Porada
Podczas tworzenia rezerwacji za pomocą interfejsu API użyj pola Potencjalny zgodnie z opisem w tabeli. Jeśli nie będzie korzystać z tego pola, mogą wystąpić nakładające się lub niedysfigurowalne rezerwacje.
Zasób Przedział czasu
| Nazwa/nazwisko | Typ | Podpis |
|---|---|---|
| Zasób | EntityReference | Odwołanie encji dla zasobu, który można zarezerwować. |
| ResourceGroup | EntityReference | Odwołanie encji do grupy zasobów, którą można zarezerwować. |
| BusinessUnit | EntityReference | Odwołanie encji do jednostki biznesowej. |
| OrganizationalUnit | EntityReference | Odwołanie encji do jednostki organizacyjnej. |
| ResourceType | Integer | Typ zasobu. Zobacz atrybut ResourceType w encji BookableResource dla możliwych zmian. |
| PoolId | Identyfikator GUID | Identyfikator puli, której członkiem jest dany zasób na czas trwania przedziału czasu. |
| CrewId | Identyfikator GUID | Identyfikator załoga, której członkiem jest dany zasób na czas trwania przedziału czasu. |
| Charakterystyki | EntityCollection | Charakterystyka zasobu, który można zarezerwować. Każda encja w kolekcji zawiera encje z informacjami o charakterystyce i klasyfikacji.
|
| HasStartLocation | logiczny | Wartość logiczna wskazująca, czy zasób ma lokalizację rozpoczęcia. |
| HasEndLocation | logiczny | Wartość logiczna wskazująca, czy zasób ma lokalizację zakończenia. |
| String | Adres e-mail zasobu. | |
| Telefon | String | Numer telefonu zasobu. |
| ImagePath | String | Ścieżka do obrazu zasobu. |
| CalendarId | Identyfikator GUID | Identyfikator kalendarza zasobu. |
Przykłady
W tym przykładzie v3 interfejsu API asystenta planowania, która umożliwia używanie wywołań internetowego interfejsu API dla wymagania o długości trwania 60 minut. Użyty jako atrybut ustawień, wyniki są filtrowane w dół. D typy zasobów są rozważane dla wyników finalnych: 1 i 2 (czyli ogólny i kontakt).
{
"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"
}
}
],
"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"
}
]
}
}
}
Poniższy przykład ilustruje prawidłowe użycie kolekcji jednostek. W tym przypadku określa 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"
}
}
],
"Territories@odata.type": "Collection(Microsoft.Dynamics.CRM.expando)",
"Territories": [
{
"@odata.type": "Microsoft.Dynamics.CRM.expando",
"value": "cc19f004-4483-ee11-8178-000d3a5c32c3"
}
]
}
}
}