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 obsługi adresu przez system:

• Popraw – adres jest niskiej jakości. Poproś o więcej informacji.
• Potwierdź – adres jest wysokiej jakości, ale różni się od adresu wejściowego. Może pojawić się prośba o potwierdzenie.
• Accept (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. Proces do użycia na podstawie zachowania „popraw, potwierdź, zaakceptuj”.
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, w której opisano dodatkowe sygnały, które mogą wymagać sprawdzenia.

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 przesyłki. 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 którekolwiek z tych stwierdzeń jest prawdziwe: validationGranularity ma wartość OTHER. addressComplete to false.
Potwierdź adres	Odpowiedź z usługi verdict wskazuje adres dostawy, ale zawiera zmiany w stosunku do pierwotnych danych wejściowych: dane zostały poprawione pod względem pisowni lub potwierdzone. 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 z tych stwierdzeń są prawdziwe: validationGranularity zawiera ROUTE addressComplete to true. hasInferredComponents jest true LUB hasReplacedComponents jest 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 z tych stwierdzeń są prawdziwe: validationGranularity zawiera PREMISE lub lepszą. 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. Są to jednak tylko rekomendacje, więc pamiętaj, że 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.	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 adresu, który może należeć do jednej z tych kategorii, znajdziesz w sekcji Non-US unconfirmed street number (Niepotwierdzony numer ulicy w kraju innym niż Stany Zjednoczone) w artykule Accept address - examples (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ć proces naprawiania, potwierdzania i akceptowania opisany powyżej. 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.

Sygnały naprawcze

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

1. Granularność 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 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 go dostarczyć.

2. Inne sygnały

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

Podejrzane komponenty	Jeśli wyliczenie 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 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 te informacje:

dpvConfirmation	Może to być N, D lub pusta wartość.

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, na który można dostarczyć przesyłkę, ale chcesz mieć większą pewność, że wynikowy adres jest tym, o który chodziło klientowi.

Aby wyświetlić klientowi odpowiedni prompt, 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 dokumentacji.

Uwaga: przy podejmowaniu decyzji, 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

Dopuszczalna jest 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 wyniku podawane są też te informacje, które pomagają 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 dotyczące adresu w Stanach Zjednoczonych

Niektóre pola mające 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

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

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 dotyczące adresu w Stanach Zjednoczonych

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

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

Zaakceptuj przykłady adresów