Opracuj logikę weryfikacji

W tym dokumencie opisujemy proces tworzenia systemu sprawdzania adresów, który obsługuje różne odpowiedzi interfejsu Address Validation API. Dowiesz się z niego, jak tworzyć logikę, aby prawidłowo korzystać z odpowiedzi, jak analizować inne sygnały z interfejsu API oraz kiedy i jak prosić klientów o dodatkowe informacje.

Ogólnie odpowiedź interfejsu API określa, w jaki sposób system powinien obsługiwać adres:

• Rozwiązanie: adres jest niskiej jakości. Powinieneś poprosić o dodatkowe informacje.
• Potwierdź – adres jest wysokiej jakości, ale różni się od adresu podawanego na wejściu. Może pojawić się prośba o potwierdzenie.
• Zaakceptuj – adres jest wysokiej jakości. Możesz zaakceptować podany adres.

Przeznaczenie klucza

Ten dokument pomoże Ci zmodyfikować system, aby najlepiej analizować odpowiedź interfejsu API i określać kolejne działania dotyczące podanych adresów. Poniżej przedstawiono przepływ danych w postaci pseudokodu.

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 sytuacji. Więcej informacji znajdziesz w instrukcjach implementacji. Możesz też użyć naszej implementacji tej logiki w ramach biblioteki Extended Component Library.

Omówienie przepływu pracy

Tabela poniżej zawiera podsumowanie 2 działań dotyczących Twojego systemu:

1. Przepływ pracy do użycia na podstawie zachowania naprawiania, potwierdzania i akceptowania.
2. Pierwszym sygnałem do sprawdzenia jest odpowiedź. 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ź z verdict wskazuje, że brakuje ważnych informacji, które należy podać. Adres zwrócony przez interfejs Address Validation API może nie być nadający się do wysyłki. Przepływ pracy W razie potrzeby sprawdź elementy adresu. Poproś klienta o naprawienie problemów z adresem. Poproś o weryfikację zaktualizowanego adresu. (Opcjonalnie) Prześlij żądanie do punktu końcowego opinii interfejsu API. Zobacz Obsługa zaktualizowanych adresów. Przejdź do adresu. Sygnały dotyczące wyroku Każda z tych sytuacji: Ustawiono validationGranularity na OTHER. Zapoznaj się z poziomami szczegółowości wartości. addressComplete to false.
Potwierdź adres	Odpowiedź z verdict wskazuje adres, do którego można wysłać wiadomość, ale wprowadziła zmiany w początkowym wejściu: dane są albo poprawione pod kątem pisowni, albo można je potwierdzić. Przepływ pracy Korekty: W razie potrzeby sprawdź elementy adresu. Poproś o weryfikację zaktualizowanego adresu. (Opcjonalnie) Prześlij żądanie do punktu końcowego opinii interfejsu API. Zobacz Obsługa zaktualizowanych adresów. Przejdź do adresu. Nie trzeba wprowadzać żadnych poprawek: (Opcjonalnie) Prześlij żądanie do punktu końcowego opinii interfejsu API. Zobacz Obsługa zaktualizowanych adresów. Przejdź do adresu. Sygnały dotyczące wyroku Wszystkie z tych stwierdzeń są prawdziwe: validationGranularity zawiera ROUTE lub lepszą wersję. Zapoznaj się z poziomami szczegółowości wartości. addressComplete to true. Pole hasInferredComponents ma wartość trueLUB pole hasReplacedComponents ma wartość true.
Zaakceptuj adres	Odpowiedź interfejsu Address Validation API wskazuje, że adres jest wysokiej jakości. Przepływ pracy Przejdź do adresu zwrotnego. Sygnały dotyczące wyroku Wszystkie z tych stwierdzeń są prawdziwe: validationGranularity zawiera PREMISE lub lepszą wersję. Zobacz wartości poziomów szczegółowości. addressComplete to true. Nie wywnioskowano ani nie zastąpiono żadnych komponentów.

Wskazówki dotyczące implementacji

Podczas projektowania sposobu, w jaki Twój system reaguje na sygnały z interfejsu Address Validation API, te zalecenia mogą Ci pomóc w utworzeniu skuteczniejszego modelu odpowiedzi. Pamiętaj jednak, że są to tylko rekomendacje, a ich wdrożenie powinno być dostosowane do Twojego modelu biznesowego.

	Wskazówki	Szczegóły
Poziom ryzyka	Podczas podejmowania decyzji o tym, czy wyświetlać prośbę o poprawki, czy zaakceptować adres w takiej postaci, w jakiej został wpisany, weź pod uwagę poziom tolerancji w danym przypadku.	Interfejs API weryfikacji adresu 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 niezweryfikowany numer ulicy, możesz go nadal zaakceptować. Jeśli jednak Twoja firma wymaga większej dokładności adresu, możesz poprosić użytkownika o jego podanie. Przykład, który może pasować do obu kategorii, znajdziesz w sekcji Niepotwierdzony numer ulicy w kraju spoza USA w artykule Akceptowane adresy – przykłady.
Akceptowanie adresów	Jeśli klient nie reaguje na prompty, warto pozwolić systemowi zaakceptować pierwotne dane.	W takich przypadkach klient może podać adres, którego nie ma w systemie, np. adres nowej budowy.
Przesyłanie opinii	Gdy ponownie wyślesz prośbę o weryfikację adresu, możesz też wysłać prośbę do punktu końcowego provideValidationFeedback.	Dzięki temu Google będzie wiedzieć, jak ostatecznie potraktowano Twoją ostateczną odpowiedź. Zobacz Obsługa zaktualizowanych adresów.

Wypróbuj wersję demonstracyjną W dalszej części tego dokumentu znajdziesz różne przykłady, które pomogą Ci zrozumieć omówiony powyżej proces naprawy, potwierdzenia i zaakceptowania. Wyniki z tych przykładów możesz sprawdzić, wpisując je w demo interfejsu Address Validation API.

Poprawianie adresu

Popraw adres, gdy wyniki wyraźnie wskazują, że nie można go dostarczyć. Twój system może poprosić klienta o podanie niezbędnych informacji, a następnie ponownie uruchomić przepływ pracy, aby uzyskać adres dostawy.

Uwaga: jeśli powtarzasz żądania interfejsu Address Validation API dotyczące tego samego adresu, możesz wywołać interfejs provideValidationFeedback, aby wskazać wynik. Zobacz Praca z adresami zaktualizowanymi

.

Poprawianie sygnałów

Interfejs API weryfikacji adresów udostępnia kilka sygnałów, które informują, czy adres wymaga poprawienia.

1. Dokładność weryfikacji i brakujące komponenty

Te 2 sygnały najlepiej wskazują adres, który może być problematyczny:

• Gdy pole validationGranularity ma wartość OTHER, system powinien zbadać sygnały komponentu adresu, aby dowiedzieć się więcej o tym, gdzie wystąpił błąd i jak go naprawić.
• Za każdym razem, gdy przetworzony obiekt address zwraca pole missingComponentTypes, Twój system powinien sprawdzić ten komponent. Brakujące elementy powodują, że adres jest niekompletny i niemożliwy do dostarczenia.

2. Inne sygnały

Interfejs API weryfikacji adresów dostarcza też inne sygnały, które pomagają zdiagnozować konkretne problemy:

Podejrzane komponenty	Jeśli enumeracja poziomu potwierdzenia dla 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, które mają zastosowanie tylko do adresów w Stanach Zjednoczonych, dostarczają przydatnego sygnału, że adres nie może zostać dostarczony i należy go poprawić. W przypadku adresu, który wymaga naprawy, powinieneś zobaczyć:

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

Szczegółowe informacje o dpvConfirmation znajdziesz w artykule Praca z adresami w Stanach Zjednoczonych.

Przykłady poprawiania adresów

Potwierdzanie adresu

Adres jest potwierdzany, gdy interfejs API weryfikacji adresów wywnioskował lub wprowadził zmiany w składnikach adresu, aby uzyskać potwierdzony adres. W takich przypadkach masz adres dostawy, ale wolisz mieć pewność, że jest to adres, który podał klient.

Aby wyświetlić klientowi odpowiednie prompty, Twoja logika musi zidentyfikować komponenty oznaczone przez usługę, aby określić, które działanie lub flagę interfejs API zastosował w przypadku danego komponentu, np. inferred, replaced lub spellCorrected. Więcej informacji znajdziesz w sekcji AddressComponent.

Uwaga: przy podejmowaniu decyzji, czy potwierdzić adres u klienta, czy uznać go za prawidłowy, weź pod uwagę poziom ryzyka. Dodatkowo, jeśli ponownie wyślesz żądania do interfejsu Address Validation API, możesz wykonać wywołanie do interfejsu provideValidationFeedback, aby wskazać wynik. Zobacz Zarządzanie zaktualizowanymi adresami.

Potwierdź sygnały

Interfejs API weryfikacji adresu udostępnia kilka sygnałów, które informują, czy adres powinien zostać potwierdzony.

1. Szczegółowość weryfikacji

Dopuszczalna jest wartość validationGranularity ROUTE lub lepsza, ale PREMISE lub SUBPREMISE zapewniają silniejszy sygnał o możliwości dostarczenia.

2. Inne sygnały

Gdy decydujesz się potwierdzić adres klienta, wyrok zawiera również te informacje, które pomogą Ci określić, które komponenty należy sprawdzić:

Dane wywnioskowane	Gdy pole hasInferredComponents ma wartość true, wiesz, że interfejs API wypełnił informacje uzyskane z innych komponentów adresu.
Zastąpione dane	Gdy pole hasReplacedComponents ma wartość true, interfejs API zastępuje wprowadzone dane danymi, które według niego czynią adres prawidłowym.

3. sygnały dotyczące adresu w Stanach Zjednoczonych,

Niektóre pola, które dotyczą tylko adresów w Stanach Zjednoczonych, wskazują, że Twoja logika powinna potwierdzić szczegóły z klientem. Wykonaj jedną z tych czynności:

dpvConfirmation	S Szczegółowe informacje o dpvConfirmation znajdziesz w artykule Praca z adresami w Stanach Zjednoczonych.
Odpowiedź na odpowiedź	Zawiera pole missingComponentType z wartością subpremise. Uwaga: jeśli pole zawiera typy inne niż subpremise, działanie zostanie zaliczone do kategorii poprawiania adresu. Pełną listę typów adresów znajdziesz w dokumentacji dotyczącej geokodowania.

Przykłady adresów do potwierdzenia

Akceptowanie adresu

Adres akceptujesz, gdy wynik jest bardzo wiarygodny i potwierdza, że adres jest prawidłowy i można go wykorzystać bez dalszej interakcji z klientem w dalszym procesie.

Akceptowanie sygnałów

Interfejs API weryfikacji adresu udostępnia kilka sygnałów, które informują, czy adres powinien zostać potwierdzony.

1. Szczegółowość weryfikacji

Dopuszczalna jest wartość validationGranularity na poziomie PREMISE lub wyższa, ale w niektórych przypadkach wartość ROUTE może wskazywać adres, na który można dostarczyć przesyłkę.

2. Inne sygnały

Wyrok dotyczący adresu o wysokiej jakości powinien też zawierać:

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

3. sygnały dotyczące adresu w Stanach Zjednoczonych,

Niektóre pola, które dotyczą tylko adresów w Stanach Zjednoczonych, wskazują na adres wysokiej jakości, na który można dostarczyć przesyłkę. W przypadku akceptowalnego adresu w Stanach Zjednoczonych powinieneś zobaczyć:

dpvConfirmation	Y Szczegółowe informacje o dpvConfirmation znajdziesz w artykule Praca z adresami w Stanach Zjednoczonych.

Przykłady adresów do zaakceptowania