Tworzenie logiki weryfikacji

W tym dokumencie opisano proces tworzenia systemu sprawdzania adresów, który obsługuje różne odpowiedzi z interfejsu Address Validation API. Dowiesz się z niego, jak utworzyć logikę, aby prawidłowo używać odpowiedzi, sprawdzać inne sygnały z interfejsu API oraz kiedy i jak prosić klientów o więcej informacji.

Ogólnie rzecz biorąc, odpowiedź interfejsu API określa, jak system powinien postępować z adresem:

• Napraw – adres jest niskiej jakości. Poproś o więcej informacji.
• Confirm – adres jest wysokiej jakości, ale różni się od adresu wejściowego. Możesz poprosić o potwierdzenie.
• Zaakceptuj – adres jest wysokiej jakości. Możesz zaakceptować podany adres.

Przeznaczenie klucza

Ten dokument pomoże Ci zmodyfikować system, aby jak najlepiej analizować odpowiedź interfejsu API i określać kolejne działania, które należy podjąć w przypadku podanych adresów. Poniższy pseudokod ilustruje możliwy proces.

if (the API response indicates significant problems in the address)
    FIX - prompt the user to fix the address
else if (the API response indicates less significant problems in the address)
    CONFIRM - confirm with the user that the address is correct
else
    ACCEPT - continue with the address returned by the API.

Dokładna logika zależy od Twojej sytuacji. Więcej informacji znajdziesz w wytycznych dotyczących implementacji. Możesz też użyć naszej implementacji tej logiki w ramach open source, która znajduje się w rozszerzonej bibliotece komponentów.

Omówienie procesu

W tabeli poniżej znajdziesz podsumowanie 2 działań, które możesz wykonać w systemie:

1. Przepływ pracy, którego należy użyć na podstawie zachowania związanego z naprawianiem, potwierdzaniem i akceptowaniem.
2. Pierwsze sygnały, które należy sprawdzić w odpowiedzi. Opisane tutaj sygnały pochodzą z usługi verdict i nie są jedynymi sygnałami, które należy sprawdzić, ale stanowią wstępny wskaźnik jakości adresu. Każdy typ zachowania odpowiada sekcji w tym dokumencie, która opisuje dodatkowe sygnały, które również mogą wymagać sprawdzenia.

zachowanie systemu,
Popraw adres	Odpowiedź z verdict wskazuje, że brakuje ważnych informacji, które należy podać. Adres zwrócony przez interfejs API może nie być prawidłowy. Przepływ pracy W razie potrzeby sprawdź komponenty adresu. Poproś klienta o rozwiązanie problemów z adresem. Poproś o zweryfikowanie zaktualizowanego adresu. Kontynuuj z adresem. Sygnały dotyczące oceny Dowolny z tych warunków: validationGranularity ustawiono na OTHER. addressComplete to false.
Potwierdź adres	Odpowiedź z usługi verdict wskazuje adres, na który można dostarczyć przesyłkę, ale wprowadziła zmiany w pierwotnych danych wejściowych: wywnioskowała dane, które zostały poprawione, lub dane, które można potwierdzić. Przepływ pracy Wymagane poprawki: W razie potrzeby sprawdź komponenty adresu. Poproś o zweryfikowanie zaktualizowanego adresu. Kontynuuj z adresem. Nie są wymagane żadne poprawki: Kontynuuj z adresem. Sygnały dotyczące oceny Muszą być spełnione wszystkie te warunki: validationGranularity zawiera ROUTE addressComplete to true. Pole hasInferredComponents ma wartość true LUB pole hasReplacedComponents ma wartość true.
Zaakceptuj adres	Odpowiedź interfejsu Address Validation API wskazuje, że adres jest doskonałej jakości. Przepływ pracy Kontynuuj, używając zwróconego adresu. Sygnały dotyczące oceny Muszą być spełnione wszystkie te warunki: validationGranularity zawiera PREMISE lub lepszy. addressComplete to true. Brak komponentów wywnioskowanych lub zastąpionych.

Wskazówki dotyczące implementacji

Podczas projektowania sposobu, w jaki system reaguje na sygnały weryfikacji adresu, te zalecenia mogą pomóc w stworzeniu skuteczniejszego modelu odpowiedzi. Są to jednak tylko zalecenia, więc pamiętaj, że wdrożenie powinno być dostosowane do Twojego modelu biznesowego.

	Wskazówki	Szczegóły
Poziom ryzyka	Podczas podejmowania decyzji, czy poprosić o poprawki, czy zaakceptować wpisany adres, weź pod uwagę poziom tolerancji w Twojej sytuacji.	Address Validation API zwraca różne sygnały, które możesz uwzględnić w poziomie ryzyka, aby zoptymalizować proces weryfikacji. Jeśli na przykład adres ma niepotwierdzony numer ulicy, możesz go zaakceptować. Jeśli jednak Twoje operacje biznesowe wymagają większej precyzji adresu, możesz poprosić użytkownika o podanie dokładniejszych informacji. Przykład, który może należeć do obu kategorii, znajdziesz w sekcji Niepotwierdzony numer domu poza USA w artykule Akceptowanie adresu – przykłady.
Akceptuj adresy	Dobrą praktyką jest umożliwienie systemowi zaakceptowania pierwotnego wpisu, jeśli klient nie odpowie na prośby.	W takich przypadkach klient mógł podać adres, którego nie ma w systemie, np. w przypadku nowego budynku.

Wypróbuj wersję demonstracyjną W dalszej części tego dokumentu znajdziesz różne przykłady, które pomogą Ci zrozumieć opisany powyżej proces naprawiania, potwierdzania i akceptowania. Wyniki tych przykładów możesz sprawdzić, wpisując je w wersji demonstracyjnej Weryfikacji adresów w Maps JavaScript API.

Poprawianie adresu

Popraw adres, jeśli wyniki wyraźnie wskazują, że nie można dostarczyć przesyłki na ten adres. System może wtedy poprosić klienta o podanie niezbędnych informacji, po czym możesz ponownie uruchomić proces, aby uzyskać adres dostawy.

Napraw sygnały

Address Validation API udostępnia szereg sygnałów, które informują, czy adres wymaga poprawienia.

1. Szczegółowość weryfikacji i brakujące komponenty

Te 2 sygnały najlepiej wskazują na problematyczny adres:

• Gdy pole validationGranularity ma wartość OTHER, system powinien sprawdzić sygnały komponentu adresu, aby dowiedzieć się więcej o tym, gdzie wystąpił błąd i jak rozwiązać problem.
• Za każdym razem, gdy przetworzony obiekt address zwraca pole missingComponentTypes, system powinien sprawdzić ten komponent. Brakujące komponenty również powodują, że adres jest niekompletny i nie można dostarczyć przesyłki.

2. Inne sygnały

Address Validation API udostępnia też inne sygnały, które pomagają diagnozować konkretne problemy:

Podejrzane komponenty	Jeśli typ wyliczeniowy poziomu potwierdzenia komponentu to UNCOMFIRMED_AND_SUSPICIOUS, prawdopodobnie komponent jest nieprawidłowy.
Nierozwiązany komponent	unresolvedToken to część danych wejściowych, która nie została rozpoznana jako prawidłowa część adresu.

3. Sygnały dotyczące adresu w USA

Niektóre pola, które mają zastosowanie tylko do adresów w USA, dostarczają przydatnych informacji o tym, że adres jest niedostępny i należy go poprawić. W przypadku adresu, który wymaga poprawienia, powinny być widoczne te informacje:

dpvConfirmation	Może to być N, D lub puste pole.

Więcej informacji o dpvConfirmation znajdziesz w artykule Obsługa adresów w Stanach Zjednoczonych.

Przykłady poprawek adresów

Potwierdzanie adresu

Adres potwierdzasz, gdy werdykt wskazuje, że interfejs Address Validation API wywnioskował lub wprowadził zmiany w komponentach adresu, aby wygenerować zweryfikowany adres. W takich przypadkach masz adres, na który można dostarczyć przesyłkę, ale chcesz mieć większą pewność, że jest to adres, który klient miał na myśli.

Aby wyświetlić klientowi odpowiedni komunikat, Twoja logika powinna zidentyfikować komponenty oznaczone przez usługę i określić, które działanie lub oznaczenie interfejs API zastosował do komponentu, np. inferred, replaced lub spellCorrected. Zobacz AddressComponent w dokumentacji.

Uwaga: przy podejmowaniu decyzji, czy potwierdzić adres z klientem, czy zaakceptować go jako prawidłowy, weź pod uwagę poziom ryzyka.

Potwierdź sygnały

Address Validation API udostępnia szereg sygnałów, które informują, czy adres powinien zostać potwierdzony.

1. Szczegółowość weryfikacji

validationGranularity na poziomie ROUTE lub wyższym jest akceptowalny, ale PREMISE lub SUBPREMISE zapewnia silniejszy sygnał dostarczalności.

2. Inne sygnały

Gdy zdecydujesz się potwierdzić wpisany adres u klienta, werdykt zawiera też te informacje, które pomogą Ci określić, jakie komponenty należy sprawdzić:

Dane wywnioskowane	Jeśli pole hasInferredComponents ma wartość true, oznacza to, że interfejs API wypełnił informacje, które uzyskał z innych komponentów adresu.
Zastąpione dane	Gdy pole hasReplacedComponents ma wartość true, interfejs API zastępuje wpisane dane danymi, które uzna za prawidłowe.

3. Sygnały dotyczące adresu w USA

Niektóre pola, które mają zastosowanie tylko do adresów w Stanach Zjednoczonych, wskazują, że Twoja logika powinna potwierdzić szczegóły z klientem. Obowiązuje jedna z tych opcji:

dpvConfirmation	S Więcej informacji o dpvConfirmation znajdziesz w artykule Obsługa adresów w Stanach Zjednoczonych.
Odpowiedź na adres	Zawiera pole missingComponentTypes o wartości subpremise. Uwaga: jeśli pole zawiera typy inne niż subpremise, działanie zostanie zaliczone do kategorii „Popraw adres”. Pełną listę typów adresów znajdziesz w dokumentacji geokodowania.

Przykłady potwierdzania adresu

Zaakceptuj adres

Adres jest akceptowany, gdy werdykt wskazuje z dużym prawdopodobieństwem, że adres jest możliwy do dostarczenia i może być używany bez dalszej interakcji z klientem w procesie dalszego przetwarzania.

Akceptowanie sygnałów

Address Validation API udostępnia szereg sygnałów, które informują, czy adres powinien zostać potwierdzony.

1. Szczegółowość weryfikacji

Wartość validationGranularity równa PREMISE lub wyższa jest akceptowalna, ale w niektórych przypadkach wartość ROUTE nadal wskazuje adres, na który można dostarczyć przesyłkę.

2. Inne sygnały

Werdykt dotyczący adresu wysokiej jakości powinien też zawierać te informacje:

• Brak zastąpionych danych. W tym przypadku hasReplacedComponents: FALSE.
• Brak wywnioskowanych komponentów. W tym przypadku: hasInferredComponents: FALSE.

3. Sygnały dotyczące adresu w USA

Niektóre pola, które mają zastosowanie tylko do adresów w Stanach Zjednoczonych, wskazują adres wysokiej jakości, pod który można dostarczyć przesyłkę. W przypadku prawidłowego adresu w USA powinny wyświetlić się te informacje:

dpvConfirmation	Y Szczegółowe informacje o  dpvConfirmation znajdziesz w artykule Obsługa adresów w Stanach Zjednoczonych.

Przykłady akceptowanych adresów