Tworzenie logiki weryfikacji

W tym dokumencie opisujemy proces tworzenia systemu sprawdzania adresów, który obsługuje różne odpowiedzi z interfejsu Address Validation API. Wyjaśniamy w nim, jak tworzyć logikę, aby prawidłowo korzystać z odpowiedzi, badać inne sygnały z interfejsu API oraz kiedy i jak prosić klientów o więcej informacji.

Odpowiedź interfejsu API określa ogólnie te sposoby, w jakie system powinien obsługiwać adres:

• Popraw – adres jest niskiej jakości. Poproś o więcej informacji.
• Potwierdzony – 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 przepływ.

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 wskazówkach dotyczących implementacji. Możesz też użyć naszej implementacji open source tej logiki, która znajduje się w bibliotece komponentów rozszerzonych.

Omówienie przepływu pracy

Tabela poniżej zawiera podsumowanie 2 działań w Twoim systemie:

1. Przepływ pracy, którego należy użyć na podstawie zachowania związanego z poprawianiem, potwierdzaniem i akceptowaniem.
2. Pierwsze sygnały do sprawdzenia 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 zawiera opis dodatkowych sygnałów, które warto sprawdzić.

Zachowanie systemu
Popraw adres	Odpowiedź od verdict wskazuje na brak ważnych informacji, które należy podać. Adres zwrócony przez interfejs API może nie być odpowiedni do dostarczenia. Przepływ pracy W razie potrzeby sprawdź komponenty adresu. Poproś klienta o rozwiązanie problemów z adresem. Poproś o weryfikację zaktualizowanego adresu. Kontynuuj z adresem. Sygnały dotyczące decyzji Spełniony jest dowolny z tych warunków: validationGranularity ustawiono na OTHER. addressComplete to false.
Potwierdź adres	Odpowiedź z verdict wskazuje adres dostawy, ale wprowadza zmiany w oryginalnym wejściu: wnioskuje dane, które są poprawione pod względem pisowni lub które można potwierdzić. Przepływ pracy Korekty: W razie potrzeby sprawdź komponenty adresu. Poproś o weryfikację zaktualizowanego adresu. Kontynuuj z adresem. Nie wymaga poprawek: Kontynuuj z adresem. Sygnały dotyczące decyzji Wszystkie te warunki muszą być spełnione: validationGranularity zawiera ROUTE addressComplete to true. hasInferredComponents jest równe true LUB hasReplacedComponents jest równe true.
Zaakceptuj adres	Odpowiedź interfejsu Address Validation API wskazuje adres o doskonałej jakości. Przepływ pracy Użyj zwróconego adresu. Sygnały dotyczące decyzji Wszystkie te warunki muszą być spełnione: validationGranularity zawiera co najmniej PREMISE. addressComplete to true. Brak wywnioskowanych lub zastąpionych komponentów.

Wskazówki dotyczące implementacji

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

	Wskazówki	Szczegóły
Poziom ryzyka	Przy określaniu równowagi między wyświetlaniem prośby o poprawki a akceptowaniem wpisanego adresu weź pod uwagę poziom tolerancji w Twojej sytuacji.	Interfejs Address Validation API zwraca różne sygnały, które możesz uwzględnić w swoim poziomie ryzyka, aby zoptymalizować proces weryfikacji. Jeśli na przykład adres ma niepotwierdzony numer ulicy, możesz go zaakceptować. Z drugiej strony, jeśli Twoja firma wymaga 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 ulicy spoza Stanów Zjednoczonych w Akceptowanie adresu – przykłady.
Akceptowanie adresów	Warto zezwolić systemowi na zaakceptowanie pierwotnego wpisu, jeśli klient nie odpowie na prośby.	W takich przypadkach klient mógł wpisać adres, którego nie ma w systemie, np. w przypadku nowej konstrukcji.

Wypróbuj wersję demonstracyjną W pozostałej 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 adresu w interfejsie Maps JavaScript API.

Poprawianie adresu

Popraw adres, gdy wyniki wyraźnie wskazują, że nie można go dostarczyć. Następnie system może poprosić klienta o podanie niezbędnych informacji, po czym ponownie uruchomić proces, aby uzyskać adres dostawy.

Naprawianie sygnałów

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

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 zbadać sygnały komponentów adresu, aby dowiedzieć się więcej o tym, gdzie wystąpił błąd i jak go naprawić.
• Gdy przetworzony obiekt address zwróci pole missingComponentTypes, Twój system powinien sprawdzić ten komponent. Brakujące komponenty również sprawiają, że adres jest niekompletny i nie można na niego dostarczyć przesyłki.

2. Inne sygnały

Interfejs Address Validation API udostępnia też inne sygnały, które pomagają w diagnozowaniu konkretnych problemów:

Podejrzane komponenty	Jeśli wartość wyliczeniowa poziomu potwierdzenia komponentu to UNCOMFIRMED_AND_SUSPICIOUS, prawdopodobnie jest on 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 adresowe w Stanach Zjednoczonych

Niektóre pola mające zastosowanie tylko do adresów w Stanach Zjednoczonych stanowią przydatny sygnał, że adres jest nieprawidłowy i należy go poprawić. W przypadku adresu, który wymaga poprawy, zobaczysz:

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 poprawionych adresów

Potwierdzanie adresu

Adres jest potwierdzany, gdy wynik wskazuje, że interfejs Address Validation API wywnioskował lub zmienił komponenty adresu, aby uzyskać zweryfikowany adres. W takich przypadkach masz adres, pod który można dostarczyć przesyłkę, ale chcesz mieć większą pewność, że wynikowy adres jest tym, który zamierzał podać klient.

Aby wyświetlić klientowi odpowiedni komunikat, logika musi zidentyfikować komponenty oznaczone przez usługę, aby określić, jakie działanie lub flagę interfejs API zastosował do komponentu, np. inferred, replaced lub spellCorrected. Więcej informacji znajdziesz w sekcji AddressComponent w bibliografii.

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

Potwierdzanie sygnałów

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

1. Szczegółowość weryfikacji

Dopuszczalny jest wynik validationGranularity na poziomie ROUTE lub wyższym, ale PREMISE lub SUBPREMISE dają silniejszy sygnał dostarczalności.

2. Inne sygnały

Decydując się na potwierdzenie adresu przez klienta, w ramach weryfikacji podajemy też te informacje, aby określić, które komponenty należy sprawdzić:

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

3. Sygnały adresowe w Stanach Zjednoczonych

Niektóre pola, które mają zastosowanie tylko w przypadku adresów w Stanach Zjednoczonych, wskazują, że logika powinna potwierdzić szczegóły z klientem. Spełniony jest jeden z tych warunków:

dpvConfirmation	S Więcej informacji o dpvConfirmation znajdziesz w artykule Obsługa adresów w Stanach Zjednoczonych.
Odpowiedź dotycząca adresu	Zawiera pole missingComponentTypes o wartości subpremise. Uwaga: jeśli pole zawiera typy inne niż subpremise, działanie zostanie zakwalifikowane do kategorii poprawiania adresu. Pełną listę typów adresów znajdziesz w dokumentacji Geocoding API.

Przykłady potwierdzania adresu

Akceptowanie adresu

Akceptujesz adres, gdy wynik wskazuje na wysoki stopień pewności, że adres jest prawidłowy i może być używany bez dalszej interakcji z klientem w procesie dalszym.

Akceptowanie sygnałów

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

1. Szczegółowość weryfikacji

Dopuszczalny jest kod validationGranularity o wartości PREMISE lub wyższej, ale w niektórych przypadkach ROUTE nadal wskazuje adres, pod 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 adresowe w Stanach Zjednoczonych

Niektóre pola mające zastosowanie tylko do adresów w Stanach Zjednoczonych wskazują adres wysokiej jakości, pod który można dostarczyć przesyłkę. Prawidłowy adres w Stanach Zjednoczonych powinien zawierać:

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

Przykłady akceptowanych adresów