Метрики за оценка на API за проследяване на пратки: 8 KPI показателя за измерване в рамките на доказателство за концепция

Оценете доказването на концепцията за API за проследяване на пратки, като използвате осем KPI: използваемо покритие на проследяването, пълнота на събитията, точност на статуса, забавяне на актуализациите, надеждност на доставката на webhook известия, надеждност на API заявките, усилия за интеграция и разход на една използваема проследена пратка. Измервайте ги спрямо действителния ви профил на доставките и договорените референтни данни, а не само спрямо успешни демонстрационни заявки. Определете критериите за приемане преди тестването, така че резултатите да подкрепят ясно решение за внедряване, отстраняване на проблеми или отхвърляне.

Това ръководство е предназначено за ръководители на инженерни екипи, екипи по логистични операции и отговорници по снабдяването, които избират API за система за управление на поръчки, складова платформа, работен процес за обслужване на клиенти или интерфейс за проследяване. Формулите по-долу са предложени методи за оценка, а не публикувани отраслови бенчмаркове. Праговете ви трябва да отразяват последствията от липсваща, забавена или неправилна информация за проследяване.

Създайте тест, който представя производствената среда

Доказването на концепцията трябва да отговори на практически въпрос: може ли тази интеграция да предоставя надеждна информация за пратките при приемливи оперативни разходи? Пясъчната среда може да потвърди, че заявките и отговорите работят, но сама по себе си не може да докаже качеството на актуалните данни от превозвачите.

Комбинирайте исторически пратки, когато подходящите записи все още са достъпни, с актуални пратки, наблюдавани по време на теста. Историческите случаи помагат за проверка на интерпретацията на статусите и необичайните маршрути. Актуалните случаи са необходими за измерване на забавянията при актуализациите и доставката на известията.

• Представете профила на вашите доставки. Включете основните превозвачи, комбинациите от начални и крайни точки, видовете услуги и трансграничните предавания, когато са приложими. Отчитайте важните сегменти отделно, вместо да ги скривате в една средна стойност.
• Включете сложни маршрути. Тествайте забавени пратки, неуспешни опити за доставка, връщания, нееднозначно идентифициране на превозвача и пратки, които все още не са получили физическо сканиране.
• Отделете отрицателните тестове. Невалидните номера за проследяване и неподдържаните заявки са полезни за тестване на обработката на грешки, но не трябва безшумно да намаляват оценката за покритие на валидните пратки.
• Съхранявайте референтните доказателства. Записвайте информацията за превозвача, времевите отпечатъци, часовата зона на източника, идентификаторите за проследяване и API отговорите, използвани във всяка оценка. Защитете личните данни и идентификационните данни в журналите.
• Договорете отговорностите. Инженерният екип трябва да отговаря за техническата инструментализация; логистичните операции трябва да потвърдят значението на пратките; финансовият отдел или снабдяването трябва да потвърдят модела на разходите.

Използвайте общ период на наблюдение и определете какво се счита за използваем резултат, преди да събирате оценките. Ако сравнявате няколко реализации, дайте на всяка една и съща група пратки и съпоставими тестови условия. Записвайте разликите в конфигурацията, които могат да повлияят на резултата.

1. Използваемо покритие на проследяването

Въпрос: Може ли API да върне полезна информация за проследяване на пратките, които вашият бизнес действително изпраща?

Формула: Използваемо покритие на проследяването = допустими тестови пратки с използваем резултат от проследяването ÷ всички допустими тестови пратки × 100.

Определете допустимостта независимо от списъка с поддържани превозвачи на доставчика. Например знаменателят ви може да включва всички валидни пратки в обхвата на планираното внедряване, които са достатъчно стари, за да е разумно да разполагат с информация за проследяване. В противен случай изключването на неподдържаните пратки би скрило пропуска в покритието, който се опитвате да измерите.

Използваем резултат трябва да означава повече от успешно регистриране или HTTP отговор за успех. Посочете минималната информация, от която се нуждае работният ви процес, например правилно идентифициран превозвач и съдържателен статус на пратката. Статусът за създадена товарителница може да е валиден преди физическото предаване, но не трябва да се счита за доказателство за по-късно събитие на движение.

Разбивайте резултатите по превозвач, направление и услуга. Разграничавайте също неподдържаните услуги, грешките при идентифициране на превозвача, пратките преди първото сканиране и временните неуспешни опити за извличане. Обобщената оценка може да изглежда приемлива, докато критично за бизнеса направление остава неизползваемо.

Правило за решение: Превърнете покритието на задължителните сегменти на доставките в условие за внедряване. Високият общ процент не трябва да компенсира неподдържан сегмент, необходим за старта.

2. Пълнота на задължителните събития

Въпрос: Улавя ли API ключовите етапи на пратката, от които се нуждаят вашите операции?

Формула: Пълнота на задължителните събития = съпоставени задължителни референтни събития ÷ всички задължителни референтни събития, наблюдавани по време на теста × 100.

Създайте набор от референтни събития от запазени записи на превозвача или друг договорен източник на истина. Определете правила за съпоставяне на описания, времеви отпечатъци, местоположения и типове събития. Не изисквайте идентичен текст, когато две описания представляват едно и също събитие, и не очаквайте всеки превозвач да публикува една и съща последователност от етапи.

За много екипи полезните етапи включват физическо приемане, движение, опити за доставка, изключения и окончателна доставка. Точният списък трябва да следва работния процес. Екипът за поддръжка може да се нуждае от събитие за опит за доставка, което не е необходимо на аналитично табло.

Съпоставяйте отделни събития, вместо да броите необработени редове. Дублираните сканирания не трябва да подобряват пълнотата. Обратно, доставчикът може да обедини излишни събития, без да губи информацията, необходима на приложението ви.

Съхранявайте недостъпните референтни записи отделно от потвърдените липсващи събития. Ако референтният източник не може да установи дали дадено събитие е съществувало, отбележете случая като нерешен, вместо да го третирате като провал или успех на доставчика.

Правило за решение: Оценявайте критичните етапи отделно. Липсваща незадължителна актуализация на местоположението не е равнозначна на липсващ опит за неуспешна доставка, който трябва да задейства действие към клиента.

3. Точност на нормализирания статус

Въпрос: Превежда ли API събитията на превозвача в правилното оперативно значение?

Формула: Точност на статуса = правилно класифицирани оценени наблюдения на статуса ÷ всички оценени наблюдения на статуса × 100.

Нека логистичните операции определят очакваните класификации, преди да прегледат изхода на API. Точната история на събитията все пак може да доведе до подвеждащ текущ статус, ако интеграцията интерпретира опит за доставка като доставка или третира движение за връщане като обикновен транзит към получателя.

Оценявайте както отделните съпоставяния на събития, така и статуса на ниво пратка. Когато е възможно, запазвайте оригиналното описание на превозвача заедно с нормализираната стойност, за да могат проверяващите да проучват разминаванията.

Използвайте матрица на объркването, за да покажете кои статуси с кои други се бъркат. Отчитайте отделно неправилните класификации като доставено, тъй като неправилен сигнал за приключване може да повлияе на съобщенията към клиентите, работните процеси за поддръжка и последващата обработка на поръчките.

Включете изрична категория „неизвестно“. Предпазливият неизвестен резултат може да е по-безопасен от неоправдан окончателен статус, но все пак се нуждае от правило за оперативна обработка. Не премахвайте неизвестните случаи от знаменателя само за да подобрите точността.

Правило за решение: Определете по-строги условия за приемане при грешки, които задействат необратими действия или действия, видими за клиента. Самата обща точност е недостатъчна, когато един тип грешка носи непропорционално висок риск.

4. Забавяне на актуализациите

Въпрос: Колко време е необходимо, за да стане ново събитие на превозвача използваемо във вашата система?

Основна мярка: Наблюдавано забавяне на актуализацията = моментът, в който системата ви устойчиво записва използваемата актуализация − моментът, в който събитието е наблюдавано за първи път в договорения референтен източник.

Записвайте отделни времеви отпечатъци за събитието на превозвача, наблюдението от вашия референтен източник, получаването на webhook известието и успешната вътрешна обработка. Тези времеви отпечатъци отговарят на различни въпроси. Времето на сканиране може да предхожда момента, в който превозвачът публикува събитието, така че изваждането само на времето на сканиране не изолира забавянето на доставчика на проследяването.

Проверките на референтния източник създават неопределеност при измерването. Ако проверявате източника на превозвача през интервали, знаете кога сте видели събитието за първи път, но не и точния момент на публикуването му. Документирайте този интервал и описвайте резултата като наблюдавано забавяне, а не като точно време за обработка от доставчика.

Когато извадката го позволява, отчитайте медианата и процентил от опашката, например p95, по важните сегменти. Включвайте размерите на извадките. Бързата медиана може да скрие дълги забавяния, засягащи по-малка, но оперативно важна група пратки.

Правило за решение: Обвържете целите за забавяне с действието. Работният процес за ежедневно отчитане и чувствителното към времето известие за изключение не трябва автоматично да споделят един и същ праг. Липсващите актуализации трябва да останат видими в отчетите за пълнота, вместо да изчезват от резултатите за забавяне.

5. Надеждност на доставката на webhook известия

Въпрос: Достигат ли очакваните актуализации до приемащото ви приложение, включително когато доставката временно е неуспешна?

Формула: Надеждност на доставката на webhook известия = различни очаквани известия, устойчиво приети в договорения прозорец ÷ всички очаквани известия × 100.

Определете набора от очаквани известия въз основа на документираните правила за абонамент, наблюдаваните промени в източника и контролираните тестове. Не приемайте, че всяко необработено сканиране от превозвача трябва да генерира отделно известие. Ако наборът от очаквани известия не може да бъде установен независимо, отчетете резултата като частичен, вместо да твърдите, че надеждността на доставката е пълна.

Тествайте временни грешки на сървъра, прекъсвания на връзката, дублирани съобщения, забавени потвърждения и възстановяване. Потвърдете документираното поведение при повторни опити и какво се случва след приключването им. Използвайте непроизводствени пратки или изолирана среда за разрушителни тестове.

Бройте различните известия, а не HTTP опитите. Повторните опити за доставка не трябва да увеличават числителя. Крайната ви точка трябва да потвърждава получаването едва след като е записала или поставила съобщението на опашка по безопасен начин съгласно дизайна на приложението.

Отчитайте отделно доставката от доставчика и вътрешната обработка. Webhook може да пристигне успешно, докато приложението ви не актуализира поръчката. Тествайте идемпотентна обработка, така че дублираните съобщения да не създават дублирани известия към клиентите.

Правило за решение: Изисквайте доказан път за възстановяване при пропуснати актуализации, а не само успешна доставка при нормални условия.

6. Надеждност на API заявките

Въпрос: Отговаря ли API успешно при очакваното от вас натоварване?

Формула: Надеждност на API заявките = валидни заявки, които връщат очакван, анализируем отговор в рамките на зададения ви таймаут ÷ всички направени валидни заявки × 100.

Определете валидна заявка чрез документираните удостоверяване, полезен товар и договорени ограничения на заявките. Отчитайте неправилно формираните заявки отделно като дефекти на интеграцията. Също така отчитайте отделно ограничаването на честотата, грешките при удостоверяване, таймаутите и грешките на сървъра, така че обобщената оценка да остане разбираема.

Тествайте регистрацията и извличането на пратки, както и другите крайни точки, които реализацията ви действително използва. Успешният тест само за четене не доказва, че масовото въвеждане ще се държи приемливо.

Измервайте процентилите на времето за отговор наред с надеждността. Разделяйте успеха от първия опит от крайния успех след повторни опити: повторните опити могат да възстановят операцията, но добавят забавяне, трафик и работа по обработката.

Ръководството на Google за Site Reliability Engineering определя забавянето, трафика, грешките и насищането като полезни сигнали за наблюдение. Приложете тази рамка към доказването на концепцията, като записвате обема на заявките и едновременността наред с отказите. Договорете ограниченията на теста за натоварване, преди да генерирате трафик.

Правило за решение: Третирайте краткия резултат от доказването на концепцията като доказателство за тестваното натоварване и период, а не като доказателство за дългосрочна наличност или заместител на договорни ангажименти.

7. Усилия за интеграция и възстановяване

Въпрос: Колко инженерна работа е необходима, за да стане интеграцията безопасна за експлоатация?

Основна мярка: Усилия за интеграция = записани инженерни часове, необходими за завършване на договорен контролен списък за готовност за производство.

Използвайте един и същ контролен списък за всяка реализация. Включете удостоверяване, регистрация, приемане на webhook известия, съпоставяне на статуси, премахване на дублирания, съгласуване, наблюдение, обработка на идентификационни данни, внедряване и оперативна документация. Отчитайте отделно изминалото календарно време и действителното инженерно време.

Измервайте работата извън първата успешна заявка. Бързата демонстрация може да остави значителна работа по обработката на грешки, историческото възстановяване и инструментите за поддръжка.

Проведете упражнение за възстановяване: прекъснете потребителя си, възстановете го и установете дали засегнатите състояния на пратките могат да бъдат съгласувани. Запишете времето за възстановяване, ръчните намеси и нерешените записи. Отбележете кои проблеми произтичат от приложението ви и кои изискват съдействие от доставчика.

Правило за решение: Сравнявайте усилията само при еквивалентна готовност. Прототип без наблюдение не трябва да изглежда по-лесен за интегриране от готова за производство реализация с тествано възстановяване.

8. Разход на една използваема проследена пратка

Въпрос: Колко ще струва получаването на информация за пратките, която отговаря на изискванията ви?

Формула: Разход на една използваема проследена пратка = общи относими оперативни разходи за периода ÷ различни пратки, отговарящи на договорените критерии за използваемост през този период.

Използвайте писмена оферта или приложимите търговски условия, вместо да предполагате как работи таксуването. Потвърдете третирането на опитите за регистрация, дублираните подавания, повторното проследяване, превишенията, историческия достъп и всички отделно таксувани услуги. Това са въпроси за проверка, а не предполагаеми такси.

Включете инфраструктурата и повтарящата се оперативна работа при изчисляването на общите вътрешни разходи. Покажете еднократните разходи за внедряване отделно или посочете периода, за който се амортизират.

Моделирайте очакваните и пиковите обеми на пратките, като използвате същия профил на доставките, тестван при доказването на концепцията. Обозначете прогнозите като оценки. Ако няма надеждни входни данни за оперативните разходи, отчетете по-тесен показател за таксите на доставчика и посочете изключените разходи.

Правило за решение: Сравнявайте разходите едва след като са изпълнени минималните изисквания за качество. Ниският разход на регистриран номер за проследяване не е непременно нисък разход за полезен резултат.

Превърнете резултатите в решение за внедряване

Създайте таблица с оценки, която съдържа определението на всеки KPI, прага за приемане, наблюдавания резултат, размера на извадката, разбивката по сегменти, нерешените случаи и отговорника. Определете праговете преди прегледа на резултатите. Няма универсален процент за успешно преминаване, който да е подходящ за всяка операция по доставки.

Използвайте задължителни критерии за критично покритие, опасни грешки в статусите, възможност за възстановяване и други неподлежи на договаряне изисквания. Прилагайте претеглено оценяване едва след преминаването на тези критерии. В противен случай ниската цена или бързото време за отговор могат математически да прикрият сериозен оперативен отказ.

Изберете един от три резултата: одобряване на внедряване с ограничен обхват, удължаване на доказването на концепцията за разрешаване на посочени неясноти или отхвърляне на тестваната конфигурация. Удължаването трябва да посочва липсващите доказателства и условието, което ще го приключи. По време на внедряването продължете да наблюдавате същите определения, така че производителността в реална среда да остане сравнима.

Ако 17TRACK е във вашия кратък списък, използвайте неговата страница на Tracking API и официалната API документация като отправни точки за потвърждаване на изискванията за интеграция, свързани с вашия тест. Прилагайте същата таблица с оценки и проверки с реални пратки; прегледът на документацията не заменя измерените резултати.

Често задавани въпроси

Колко пратки трябва да включва доказването на концепцията за API за проследяване?

Няма универсален размер на извадката. Включете достатъчно наблюдения, за да оцените всеки критичен за бизнеса сегмент и важните за работните ви процеси изключения. Показвайте броя по сегменти и неопределеността. Голяма извадка, концентрирана върху един превозвач, не може да установи надеждността при непроверени превозвачи или маршрути.

Може ли пясъчната среда да замени тестването с реални пратки?

Пясъчната среда може да потвърди създаването на заявки, анализа и поведението на приложението. Сама по себе си тя не може да установи пълнотата на актуалните събития, забавянията при публикуване от превозвача или производителността на известията в реална среда. Използвайте я заедно с тестване на реални пратки, а не като негов заместител.

Какво да направим, ако уебсайтът на превозвача и API не съвпадат?

Съхранете и двата записа с времената на наблюдение. Проверете преобразуването на часовата зона, идентичността на пратката, времето на публикуване и интерпретацията на статуса, преди да определите отговорността. Ако нито един източник не разрешава несъответствието, отбележете го като нерешено и го проучете, вместо насилствено да му приписвате етикет за успех или неуспех.

Трябва ли липсващите събития да се броят като бавни актуализации?

Поддържайте мерките отделни. Събитие, което никога не пристига, е неуспех по отношение на пълнотата или нерешен случай в зависимост от доказателствата. Забавянето измерва събитията, които пристигат. Отчитайте и двете заедно, така че липсващите събития да не правят ефективността при забавянето изкуствено добра.

Какво трябва да се случи след успешно преминаване на доказването на концепцията?

Внедрете в контролиран обхват, запазете процедурите за съгласуване и връщане назад и продължете да наблюдавате същите KPI. Разширявайте обхвата само когато резултатите в реална среда го подкрепят. Направете повторна оценка при промяна на профила на превозвачите, обема на пратките, конфигурацията на интеграцията или търговските условия.

Източници

• Google Site Reliability Engineering: Monitoring Distributed Systems — принципи за наблюдение, залегнали в обсъждането на надеждността на заявките, включително забавяне, трафик, грешки и насищане.
• 17TRACK Tracking API — официален продуктов справочник за екипи, обмислящи оценка на API на 17TRACK.
• 17TRACK API Documentation — официален справочник с документация за проверка на изискванията за интеграция преди проектиране на специфични за реализацията тестове.