Wywołania zewnętrzne

Wywołania zewnętrzne umożliwiają pozyskiwanie danych z interfejsów API spoza usługi Microsoft Dynamics 365 Fraud Protection, a następnie używanie tych danych do podejmowania świadomych decyzji w czasie rzeczywistym. Na przykład adresy innych firm i usługi weryfikacji telefonu lub własne niestandardowe modele oceniania mogą zapewnić krytyczne dane wejściowe, które pomagają określić poziom ryzyka dla niektórych zdarzeń. Za pomocą wywołań zewnętrznych można nawiązać połączenie z dowolnym punktem końcowym interfejsu API, wysłać żądanie do tego punktu końcowego z poziomu reguły zgodnie z potrzebami i użyć odpowiedzi z tego punktu końcowego, aby podjąć decyzję.

Uwaga

Jeśli te dodatkowe dane są potrzebne dla wszystkich zdarzeń, można je również wysłać w ramach schematu oceny. Aby uzyskać więcej informacji na temat wysyłania niestandardowych danych w ramach żądania interfejsu API, zobacz Przykładowe dane niestandardowe.

Typy interfejsów API, które mogą być używane w wywołaniu zewnętrznym

Przed utworzeniem wywołania zewnętrznego należy wiedzieć o następujących ograniczeniach:

• Ochrona przed oszustwami obsługuje obecnie tylko następujące metody uwierzytelniania: Anonimowe i AAD.
• Ochrona przed oszustwami obsługuje obecnie tylko następujące metody HTTP: GET i POST.

Tworzenie wywołania zewnętrznego

1. W portalu ochrony przed oszustwami w obszarze nawigacji po lewej stronie wybierz pozycję Połączenia zewnętrzne, a następnie wybierz pozycję Nowe wywołanie zewnętrzne.

2. Przejrzyj i ustaw następujące pola zgodnie z wymaganiami.

   • Nazwa — wprowadź nazwę, która będzie używana do odwoływania się do wywołania zewnętrznego z reguł. Nazwa może zawierać tylko cyfry, litery i podkreślenia. Nie może zaczynać się od liczby.

     Uwaga

     Nie można zmienić nazwy wywołania zewnętrznego po użyciu jej w regule.

   • Opis — dodaj opis, aby ułatwić zespołowi szybkie zidentyfikowanie wywołania zewnętrznego.

   • Żądanie internetowe — wybierz odpowiednią metodę HTTP (GET lub POST), a następnie wprowadź punkt końcowy interfejsu API.

     Uwaga

     Obsługiwane są tylko punkty końcowe HTTPS.

   • Włącz okresowe wywołania rozgrzewki — jeśli ruch do zewnętrznego punktu końcowego wywołania jest zbyt niski, połączenie może być zimne i może zwiększyć opóźnienie odpowiedzi z usługi zewnętrznej. Aby rozwiązać ten problem, włącz rozgrzewkę wywołań ze strony Konfiguracja wywołań zewnętrznych. Użyj przełącznika , aby włączyć wywołania rozgrzewki. Musisz podać prawidłowy adres URL GET Keep-alive. Podobnie jak w przypadku podstawowego punktu końcowego, punkt końcowy o zachowaniu aktywności musi również przejść testowe połączenie. Jeśli skonfigurujesz wywołanie zewnętrzne z włączonymi wywołaniami rozgrzewkami, gdy ruch spada zbyt nisko, usługa Fraud Protection automatycznie wykonuje anonimowe wywołania rozgrzewki do punktu końcowego o zachowaniu aktywności tylko przy użyciu metody GET.

     Uwaga

     W wywołaniach rozgrzewki nie można używać żadnych parametrów, konfiguracji ani konfigurowalnych nagłówków.

   • Uwierzytelnianie — wybierz metodę, która ma być używana do uwierzytelniania żądań przychodzących.

     • Jeśli wybierzesz pozycję Anonimowe, nagłówek autoryzacji nie zostanie wysłany.
     • W przypadku wybrania usługi AAD token usługi Azure Active Directory (Azure AD) jest generowany w dzierżawie, a > elementu nośnego jest używany jako nagłówek autoryzacji.

     Aby uzyskać więcej informacji na temat uwierzytelniania, autoryzacji i tokenów usługi Azure AD, zobacz sekcję Omówienie uwierzytelniania i autoryzacji w dalszej części tego artykułu.

   • Odbiorcy — jeśli wybierzesz usługę AAD jako metodę uwierzytelniania, zostanie wyświetlony monit o podanie odbiorców. Istniejącą aplikację platformy Azure można użyć jako odbiorców lub utworzyć nową za pośrednictwem środowiska integracji w portalu ochrony przed oszustwami. Upewnij się, że odbiorcy mają uprawnienia dostępu do zewnętrznego wywołania/usługi. Aby dowiedzieć się więcej na temat konfigurowania uwierzytelniania usługi Azure Active Directory (Azure AD), zobacz Konfigurowanie uwierzytelniania usługi Azure AD.

   • Identyfikator aplikacji — należy również podać identyfikator aplikacji nowej lub istniejącej aplikacji usługi Azure AD w ramach dzierżawy subskrypcji usługi Fraud Protection. Wygeneruj certyfikat w usłudze Azure Key Vault. Aplikacja Ochrona przed oszustwami powinna mieć dostęp do odczytu do tej usługi Azure Key Vault. Załaduj certyfikat do tej aplikacji usługi Azure AD. Aby uzyskać więcej informacji na temat tworzenia aplikacji usługi Azure AD i zarządzania nimi, zobacz Tworzenie aplikacji usługi Azure Active Directory.

   • Adres URL certyfikatu — podaj adres URL identyfikatora certyfikatu z usługi Azure Key Vault. Jest to ten sam certyfikat, który został załadowany do aplikacji usługi Azure AD w poprzednim kroku. Aby uzyskać więcej informacji na temat generowania certyfikatu w usłudze Azure Key Vault, zobacz Tworzenie i scalanie żądania podpisania certyfikatu w usłudze Azure Key Vault

   • Dodaj parametr — możesz użyć parametrów, aby przekazać dane z usługi Fraud Protection do punktu końcowego interfejsu API. W zależności od wybranej metody HTTP te parametry są wysyłane do punktu końcowego w ciągu zapytania lub w ramach treści żądania.

     Dla każdego parametru można dodać przykładowe wartości. Usługa Fraud Protection używa tych wartości parametrów, aby wykonać przykładowe wywołanie punktu końcowego przed utworzeniem lub za każdym razem, gdy wybierzesz pozycję Testuj.

     Uwaga

     Wszystkie wartości parametrów są interpretowane jako ciągi.

   • Przykładowe żądanie — podaj przykład żądania wysyłanego do połączenia zewnętrznego. Żądanie powinno odzwierciedlać podane nazwy parametrów i wartości i nie można go edytować.

     W przypadku metod GET wyświetlany jest adres URL żądania. W przypadku metod POST wyświetlana jest treść żądania.

     Przykładowe żądanie służy do wykonania przykładowego wywołania punktu końcowego przed utworzeniem lub za każdym razem, gdy wybierzesz pozycję Testuj.

   • Przykładowa odpowiedź — podaj przykład danych zwracanych w pomyślnej odpowiedzi z punktu końcowego interfejsu API. Te dane powinny być w formacie JavaScript Object Notation (JSON) i mogą być przywołyne w regułach. Przykład podany w tym miejscu jest wyświetlany podczas tworzenia reguł.

     Wybierz pozycję Testuj , aby automatycznie wprowadzić rzeczywistą odpowiedź z interfejsu API w tym polu.

   • limit czasu — określ, jak długo( w milisekundach) żądanie powinno czekać przed upływem limitu czasu. Musisz określić liczbę z zakresu od 1 do 5000.

   • Odpowiedź domyślna — określ domyślną odpowiedź , która ma zostać zwrócona, jeśli żądanie zakończy się niepowodzeniem lub przekroczy określony limit czasu. Wartość musi być prawidłowym obiektem JSON lub elementem JSON.

3. Opcjonalnie: Aby wysłać przykładowe żądanie do punktu końcowego interfejsu API i wyświetlić odpowiedź, wybierz pozycję Testuj. Aby uzyskać więcej informacji, zobacz następną sekcję Testowanie wywołania zewnętrznego.

4. Po zakończeniu ustawiania wymaganych pól wybierz pozycję Utwórz.

Testowanie wywołania zewnętrznego

Aby upewnić się, że usługa Fraud Protection może nawiązać połączenie z punktem końcowym, przetestuj połączenie w dowolnym momencie.

• Aby przetestować połączenie podczas tworzenia nowego wywołania zewnętrznego lub edytowania istniejącego wywołania zewnętrznego, ustaw wszystkie wymagane pola, a następnie wybierz pozycję Testuj.

  Usługa Fraud Protection używa podanego punktu końcowego i parametrów w celu wysłania żądania do wywołania zewnętrznego.

  • Jeśli ochrona przed oszustwami pomyślnie osiągnie docelowy punkt końcowy, w górnej części panelu pojawi się zielony pasek komunikatów informujący o pomyślnym nawiązaniu połączenia. Aby wyświetlić pełną odpowiedź, wybierz pozycję Zobacz szczegóły odpowiedzi.
  • Jeśli ochrona przed oszustwem nie może uzyskać dostępu do docelowego punktu końcowego lub jeśli nie otrzyma odpowiedzi przed upływem określonego limitu czasu, w górnej części panelu pojawi się czerwony pasek komunikatu i zostanie wyświetlony błąd, który został napotkany. Aby wyświetlić więcej informacji o błędzie, wybierz pozycję Zobacz szczegóły błędu.

Monitorowanie wywołań zewnętrznych

Monitorowanie wywołań zewnętrznych w portalu ochrony przed oszustwami

Usługa Fraud Protection zawiera kafelek zawierający trzy metryki dla każdego zdefiniowanego wywołania zewnętrznego:

• Żądania na sekundę — łączna liczba żądań podzielona przez łączną liczbę minut w wybranym przedziale czasu.
• średnie opóźnienie — łączna liczba opóźnień żądań podzielona przez łączną liczbę minut w wybranym przedziale czasu.
• Współczynnik powodzenia — łączna liczba żądań zakończonych powodzeniem podzielona przez łączną liczbę wykonanych żądań.

Liczby i wykresy wyświetlane na tym kafelku obejmują tylko dane dla przedziału czasu wybranego na liście rozwijanej w prawym górnym rogu strony.

Uwaga

Metryki są wyświetlane tylko wtedy, gdy wywołanie zewnętrzne jest używane w aktywnej regule.

1. Aby dowiedzieć się więcej na temat danych dotyczących wywołania zewnętrznego, wybierz pozycję Wydajność w prawym rogu kafelka.

   Ochrona przed oszustwami przedstawia nową stronę, która ma bardziej szczegółowy widok metryk.

2. Aby wyświetlić metryki dla dowolnego przedziału czasu w ciągu ostatnich trzech miesięcy, dostosuj ustawienie Zakres dat w górnej części strony.

Oprócz trzech opisanych wcześniej metryk zostanie wyświetlony wykres Błąd . Ten wykres przedstawia liczbę błędów według typu błędu i kodu. Aby wyświetlić liczbę błędów w czasie lub wyświetlić rozkład błędów, wybierz pozycję Wykres kołowy.

Oprócz błędów klienta HTTP (400, 401 i 403) mogą wystąpić następujące błędy:

• Nieprawidłowy identyfikator aplikacji — podany identyfikator aplikacji nie istnieje w dzierżawie lub jest nieprawidłowy.
• Niepowodzenie usługi AAD — nie można pobrać tokenu usługi Azure AD.
• Nie można odnaleźć definicji — wywołanie zewnętrzne zostało usunięte, ale nadal występuje w regule.
• Limit czasu — żądanie do celu trwało dłużej niż określony limit czasu.
• Błąd komunikacji — nie można nawiązać połączenia z obiektem docelowym z powodu problemu z siecią lub z powodu niedostępności obiektu docelowego.
• Wyłącznik — jeśli wywołanie zewnętrzne nie powiodło się w sposób ciągły i przekroczyło określony próg, wszystkie kolejne wywołania są zawieszone przez krótki interwał.
• Nieznany błąd — wystąpił wewnętrzny błąd usługi Dynamics 365.

Monitorowanie wywołań zewnętrznych za pomocą śledzenia zdarzeń

Funkcja śledzenia zdarzeń usługi Fraud Protection umożliwia przekazywanie zdarzeń związanych z zewnętrznymi wywołaniami do własnych wystąpień usługi Azure Event Hubs lub usługi Azure Blob Storage. W portalu ochrony przed oszustwami na stronie Śledzenie zdarzeń możesz zasubskrybować następujące dwa zdarzenia związane z wywołaniami zewnętrznymi:

• FraudProtection.Monitoring.ExternalCalls
• FraudProtection.Errors.ExternalCalls

Za każdym razem, gdy żądanie jest wysyłane do wywołania zewnętrznego, zdarzenie jest wysyłane do przestrzeni nazw FraudProtection.Monitoring.ExternalCalls. Ładunek zdarzenia zawiera informacje o opóźnieniu wywołania, stanie żądania oraz regule i klauzuli, z której zostało wyzwolone żądanie.

Gdy wywołanie zewnętrzne zakończy się niepowodzeniem, zdarzenie jest wysyłane do przestrzeni nazw FraudProtection.Errors.ExternalCalls. Ładunek zdarzenia zawiera żądanie identyfikatora URI i treść, które zostały wysłane do wywołania zewnętrznego, oraz odebraną odpowiedź.

Aby uzyskać więcej informacji na temat śledzenia zdarzeń, sposobu subskrybowania zdarzeń i czynności, które można wykonywać za pomocą zdarzeń, zobacz Śledzenie zdarzeń.

Aby uzyskać informacje na temat sposobu integrowania tych danych z przepływami pracy twojej organizacji oraz konfigurowania niestandardowego monitorowania, alertów i raportowania, zobacz Rozszerzalność za pośrednictwem usługi Event Hubs.

Zarządzanie wywołaniami zewnętrznymi

• Aby edytować istniejące wywołanie zewnętrzne, wybierz pozycję Edytuj w nagłówku karty.

  Uwaga

  Nie można zmienić nazwy i parametrów wywołania zewnętrznego po użyciu jej w regule.

• Aby usunąć istniejące wywołanie zewnętrzne, wybierz wielokropek (...), a następnie wybierz pozycję Usuń.

  Uwaga

  Nie można usunąć wywołania zewnętrznego po odwołaniu się do niego w regule.

• Aby wyświetlić szczegółowe metryki wydajności dla wywołania zewnętrznego, wybierz pozycję Wydajność.

• Aby przetestować, czy usługa Fraud Protection nadal może nawiązać połączenie z połączeniem zewnętrznym, wybierz wielokropek (...), a następnie wybierz pozycję Testuj połączenie.

Używanie wywołania zewnętrznego w regułach

Aby użyć zewnętrznych wywołań do podejmowania decyzji, odwołaj się do nich z reguł.

Aby na przykład odwołać się do wywołania zewnętrznego o nazwie myCall w regule, użyj następującej składni:

External.myCall()

Jeśli myCall wymaga parametru, takiego jak IPaddress, użyj następującej składni:

External.myCall(@"device.ipAddress")

Aby uzyskać informacje o języku reguł i sposobie używania wywołań zewnętrznych w regułach, zobacz Przewodnik po dokumentacji języka.

Uwaga

Jeśli wywołania zewnętrzne są używane w regule, opóźnienie reguły może wzrosnąć.

Omówienie uwierzytelniania i autoryzacji

Aby zapewnić bezpieczny dostęp do danych, interfejsy API często uwierzytelniają nadawcę żądania, aby sprawdzić, czy mają uprawnienia dostępu do danych. Wywołania zewnętrzne w usłudze Fraud Protection obsługują dwie metody uwierzytelniania: Anonimowe i AAD.

Jeśli wybierzesz pozycję Anonimowe, nagłówek autoryzacji w żądaniu HTTP do docelowego punktu końcowego pozostanie pusty. Użyj tej opcji, gdy docelowy punkt końcowy nie wymaga nagłówka autoryzacji. Jeśli na przykład punkt końcowy używa klucza interfejsu API, skonfiguruj parę klucz-wartość jako część adresu URL żądania wprowadzonego w polu Żądanie internetowe. Docelowy punkt końcowy może następnie sprawdzić, czy klucz interfejsu API z adresu URL żądania jest dozwolony, a następnie zdecydować, czy ma zostać przyznane uprawnienie.

W przypadku wybrania usługi AAD nagłówek autoryzacji w żądaniu HTTP do docelowego punktu końcowego zawiera token elementu nośnego. Token elementu nośnego to token internetowy JSON (JWT), który jest wystawiany przez usługę Azure AD. Aby uzyskać informacje o JWTs, zobacz Platforma tożsamości Microsoft tokeny dostępu. Usługa Fraud Protection dołącza wartość tokenu do tekstu "Bearer" w wymaganym formacie w nagłówku autoryzacji żądania, jak pokazano poniżej:

Token elementu nośnego <>

Oświadczenia tokenu

W poniższej tabeli wymieniono oświadczenia, których można oczekiwać w tokenach elementu nośnego wystawionych przez usługę Fraud Protection.

Nazwisko	Oświadczenie	opis
Identyfikator dzierżawy	Tid	To oświadczenie identyfikuje identyfikator dzierżawy platformy Azure subskrypcji skojarzonej z kontem usługi Fraud Protection. Aby uzyskać informacje na temat znajdowania identyfikatora dzierżawy w portalu ochrony przed oszustwami, zobacz Wymagane identyfikatory i informacje. Aby uzyskać informacje na temat znajdowania identyfikatora dzierżawy w witrynie Azure Portal, zobacz Jak znaleźć identyfikator dzierżawy usługi Azure Active Directory.
Odbiorcy	Aud	To oświadczenie identyfikuje zamierzonego adresata tokenu. Wartość dokładnie odzwierciedla identyfikator aplikacji podany podczas konfigurowania wywołania zewnętrznego w portalu ochrony przed oszustwami.
Application ID	appid	To oświadczenie to identyfikator aplikacji usługi Fraud Protection: * bf04bdab-e06f-44f3-9821-d3af64fc93a9*. Ten identyfikator jest własnością wyłącznie przez usługę Fraud Protection i tylko firma Microsoft może zażądać tokenu w jego imieniu.

Gdy interfejs API odbiera token, powinien otworzyć token i sprawdzić, czy każdy z powyższych oświadczeń jest zgodny z jego opisem.

Oto przykład pokazujący, jak można uwierzytelnić żądanie przychodzące przy użyciu programu JwtSecurityTokenHandler.

string authHeader = "Bearer <token>"; // the Authorization header value
var jwt = new JwtSecurityTokenHandler().ReadJwtToken(token);
string tid = jwt.Claims.Where(c => c.Type == "tid").FirstOrDefault()?.Value;
string aud = jwt.Claims.Where(c => c.Type == "aud").FirstOrDefault()?.Value;
string appid = jwt.Claims.Where(c => c.Type == "appid").FirstOrDefault()?.Value;
if(tid != "<my tenant id>" || aud != "<my application id>" || appid != "bf04bdab-e06f-44f3-9821-d3af64fc93a9")
{
    throw new Exception("the token is not authorized.");
}

Rozwiązania dotyczące danych zewnętrznych

Użytkownik przyjmuje do wiadomości, że odpowiada za przestrzeganie wszystkich obowiązujących przepisów i przepisów, w tym bez ograniczeń dotyczących ochrony danych, ograniczeń umownych i/lub zasad związanych z zestawami danych, które udostępniasz firmie Microsoft za pośrednictwem funkcji Zewnętrzne wywołania ochrony przed oszustwami. Ponadto użytkownik uznaje, że korzystanie z ochrony przed oszustwami podlega ograniczeniom określonym w Umowa z Klientem Microsoft, w którym stwierdza się, że użytkownik nie może korzystać z ochrony przed oszustwami (i) jako jedyny czynnik określający, czy kontynuować transakcję płatności; ii) jako czynnik określający status finansowy każdej osoby, historię finansową, zdolności kredytowe lub uprawnienia do ubezpieczenia, mieszkalnictwa lub zatrudnienia; lub (iii) do podejmowania decyzji, które powodują skutki prawne lub znacząco wpływają na osobę. Użytkownik nie może również udostępniać lub w inny sposób używać poufnych lub wysoce regulowanych typów danych w związku z korzystaniem z funkcji połączeń zewnętrznych funkcji ochrony przed oszustwami. Pośmiń czas na przejrzenie dowolnego zestawu danych lub typów danych przed ich użyciem z funkcją wywołań zewnętrznych funkcji ochrony przed oszustwami, aby upewnić się, że jest ona zgodna z tą aprowizowaniem. Firma Microsoft zastrzega sobie również prawo do sprawdzenia, czy użytkownik jest zgodny z tą aprowizację.

Dodatkowe zasoby

• Wideo: Dowiedz się więcej o nowej funkcji wywołań zewnętrznych w usłudze Dynamics 365 Fraud Protection
• Blog: Dostosowywanie ochrony przy użyciu nowych funkcji w wersji zapoznawczej usługi Dynamics 365 Fraud Protection: Podejmowanie świadomych decyzji w czasie rzeczywistym przy użyciu połączeń zewnętrznych