ធ្វើដូចម្តេចដើម្បីស្វែងរកប៉ុស្តិ៍ដឹកជញ្ជូននៅជិតជាមួយ API ?

ដើម្បីស្វែងរកប៉ុស្តិ៍នៅជុំវិញចំណុចមួយ អ្នកត្រូវផ្តល់សមាមាត្រអក្សរ បណ្ដោយ និងជ្រុង ជាមួយជ្រុងមួយទៅ API ជិតខាង។ បន្ទាប់មកពិនិត្យស្ថានភាពនៃការឆ្លើយតប, ធាតុដែលបានត្រឡប់មក និងព័ត៌មានគ្របដណ្តប់មុនបង្ហាញបញ្ជី ឬផែនទី។

នៅក្នុងកិច្ចសន្យា ROOTE roote-1.0.0, ផ្លូវ GET /v1/transit/nearby ស្វែងរកកន្លែងដឹកជញ្ជូននៅជិត។ វាមិនទទួលបានការចេញដំណើរឬសារជូនដំណឹងពេលពិតឡើយ។ ការស្វែងរកកន្លែង និងការស្វែងរកដំណើរឆ្លើយតបបន្ទាប់គឺជាដំណើរការផ្សេងគ្នា។

កំណត់ប៉ារ៉ាម៉ែត្រ

សំណើប្រើ lat ទៅសមាមាត្រ និង lng ទៅបណ្តោយ។ អាលីយ៉ាស lon ក៏ត្រូវបានរៀបរាប់នៅក្នុងកិច្ចសន្យា។ ប៉ារ៉ាម៉ែត្រ radius បង្ហាញជ្រុងជាម៉ែត្រ; limit កំណត់ចំនួនលទ្ធផលដែលទាមទារ។ ឧបករណ៍ modes អាចបញ្ជាក់ប្រភេទដឹកជញ្ជូនបាន។

សមាមាត្រទាំងនេះគេប្រើជាឧទាហរណ៍ស្វែងរកនៅ Bordeaux; វាមិនបានបង្ហាញពីប៉ុស្តិ៍ដែលបានធានាទេ។ សូមពិនិត្យមើល កិច្ចសន្យា OpenAPI ROOTE សម្រាប់ដែនកំណត់, កន្លែង និងលក្ខខណ្ឌបច្ចុប្បន្ន។

ផ្ញើសំណើដំបូងនៅខាងម៉ាស៊ីនបម្រើ

នេះគឺជាឧទាហរណ៍ JavaScript សម្រាប់បរិយាកាស Node.js ដែលមាន fetch។ តោន, បើអ្នកប្រើប្រាស់វា, ត្រូវរក្សាទុកនៅក្នុងអថេរបរិយាកាសនៅផ្នែកម៉ាស៊ីនបម្រើ។ អត្រានេះមិនចាំបាច់ដាក់សម្ងាត់នៅក្នុងកម្មវិធីរកមើលទេ។

async function rechercherArrets(token = process.env.ROOTE_API_TOKEN) {
  const url = new URL('https://api.roote.ai/v1/transit/nearby');
  url.search = new URLSearchParams({
    lat: '44.8378',
    lng: '-0.5792',
    radius: '600',
    limit: '10',
    modes: 'bus,tram'
  }).toString();

  const headers = { Accept: 'application/json' };
  if (token) headers.Authorization = `Bearer ${token}`;

  const response = await fetch(url, {
    headers,
    signal: AbortSignal.timeout(10000)
  });
  if (!response.ok) {
    throw new Error(`Erreur HTTP ${response.status}`);
  }

  const data = await response.json();
  if (data.contract_version !== 'roote-1.0.0') {
    throw new Error('Version du contrat non reconnue');
  }
  if (!['success', 'empty', 'partial'].includes(data.status)) {
    throw new Error('Recherche indisponible');
  }
  if (!Array.isArray(data.stations)) {
    throw new Error('Réponse sans collection stations valide');
  }

  return {
    status: data.status,
    stations: data.stations,
    lines: data.lines,
    operators: data.operators,
    coverage: data.coverage,
    warnings: data.warnings,
    attributions: data.attributions,
    meta: data.meta
  };
}

កិច្ចសន្យាដែលបានពិនិត្យអនុញ្ញាតឲ្យចូលដោយគ្មានអត្តសញ្ញាណ ឬតាមតោន គិតតាមគោលការណ៍ដែលអនុវត្ត។ សូមពិនិត្យសិទ្ធិ និងដែនកំណត់ការចូលរបស់អ្នក។ ការឆ្លើយតប HTTP ត្រឹមត្រូវមិនបានជំនួសការត្រួតពិនិត្យខ្លួនវាឡើយ; នៅក្នុងការផលិត, សូមប្រើការត្រួតពិនិត្យវត្ថុទៅតាម schema ផងដែរ។

អានធាតុ និងសម្ព័ន្ធរបស់ពួកវា

បណ្ដុំនៃស្ថានីយមានកន្លែងដែលបានត្រឡប់មក។ សម្រាប់មួយៗ សូមពិនិត្យអត្តសញ្ញាណ id, ឈ្មោះ name, ប្រភេទ entity_kind, ទីតាំង location និងចម្ងាយ distance_meters។ លេខសំគាល់ line_ids និង operator_ids អនុញ្ញាតឲ្យភ្ជាប់ជាមួយបណ្ដុំ lines និង operators ប្រសិនបើមាន។

បង្ហាញចម្ងាយភូមិសាស្ត្រដូច្នេះហើយ។ មិនត្រូវបំលែងវាជាពេលដំណើរក្នុងការដើរបើគ្មានការគណនាតាមផ្លូវនាំ។ មគ្គុទេសក៏ រកប៉ុស្តិ៍ជិតខាង ឲ្យពិភាក្សាហេតុផលដែលការចូលប្រើអាចបំប្លែងចរាចរណ៍ផ្លូវ។

ក៏ដូចជាការព្យាបាលព័ត៌មានមិនដែលបានដឹងជាក់លាក់ផងដែរ។ នៅក្នុងកិច្ចសន្យា accessibility.wheelchair អាចមាន តម្លៃ unknown : តម្លៃនេះមិនសមនឹង yes ឬ no ទេ។ សមត្ថភាពចេញដំណើរដែលបានផ្សាយមិនមែនជាបញ្ជីចេញដំណើរទេ។

បង្ហាញបញ្ជី ឬផែនទី

ប្រើ id ដើម្បីធានាបានថាធាតុ UI មានស្ថេរភាព, ឈ្មោះសម្រាប់ស្លាក និងទីតាំងសម្រាប់ទីតាំងរបស់ពួកវា។ ភ្ជាប់បន្ទាត់ដោយសារ line_ids ជំនួសការ​ប្រើឈ្មោះទៅជិតគ្នា។

បើអ្នកបង្ហាញពណ៌បន្ទាត់ ឬស្លាកទាំងពីរដែលបានទទួលពីទិន្នន័យ សូមទទួលយកពួកវាជាឯកសារខាងក្រៅដែលត្រូវត្រួតពិនិត្យ។ សម្រាប់ឈ្មោះ សូមប្រើអត្ថបទជាជម្រើស មិនមែន HTML ដែលចាក់ចូល។

រក្សាទុកការចាត់ចែងប្រភព និងបង្ហាញការចាត់ចែងដែលកិច្ចសន្យារបស់អ្នកបានបញ្ជាក់ថាត្រូវបានទាមទារ។

គ្រប់គ្រងលទ្ធផលទទេ, ការឆ្លើយតបផ្នែក និងកំហុស

លទ្ធផល empty បង្ហាញការស្វែងរកមិនមានលទ្ធផលនៅក្នុងដែនដឹង។ វាមិនបញ្ជាក់ពីការខ្វះខាតហេដ្ឋារចនាសម្ព័ន្ធដឹកជញ្ជូនជាក់ស្តែង។ ការឆ្លើយតប partial អាចមានកន្លែងដែលមានប្រយោជន៍ ខណៈពេលបញ្ជាក់ដែនកំណត់៖ បង្ហាញលទ្ធផលនិងការព្រមានដែលសមរម្យ។

អាន coverage, warnings និងដែនកំណត់នៅក្នុង meta។ បញ្ជីដែលត្រូវបានកាត់ខ្លីមិនបានពណ៌នាអំពីការគ្របដណ្តប់ពេញលេញ។ ប្រសិនបើកើតមានកំហុសបណ្ដាញ ឬ HTTP សូមបង្ហាញថាគ្មានស្រាប់ ដោយមិនប្តូរលទ្ធផលជាប៉ុស្តិ៍ទេ។

សម្រាប់កូដ ៤២៩ សូមពិនិត្យនូវការណែនាំពីការបន្ត និងក្បាលតំណរ របស់សេវាកម្ម។ កុំធ្វើការចាប់ផ្តើមឡើងវិញជារង្វង់។

ផ្សំខុសគ្នារវាងស្ថានីយ, តំបន់ និងទំពារ

កន្លែង entity_kind ចែកចាយកម្រិតនៃកន្លែងផ្សេងៗ។ លទ្ធផលពីរដែលនៅជិតគ្នាអាចជាទំពារផ្សេង; ឈ្មោះដែលស្រដៀងគ្នាអាចជាមកពីប្រភពផ្សេងៗ។

កុំបញ្ចូលកន្លែងដោយស្វ័យប្រវត្តិឡើយនៅលើការជិតស្និតគ្នាតែមួយ។ ប្រើសម្ព័ន្ធ និងអត្តសញ្ញាណដែលបានចេញផ្សាយដោយសេវាកម្ម។ មគ្គុទេសក៍របស់យើង GTFS, GTFS-RT និង GBFS ពន្យល់ពីបរិបទនៃទិន្នន័យ។

រៀបចំការរួមបញ្ចូលនៅក្នុងការផលិត

ចាប់ផ្តើមការស្វែងរកនៅពេលទីតាំងឬម៉ាស៊ីនចង្អុលបញ្ជាប្រែប្រួលយ៉ាងមានប្រយោជន៍។ ក្រុមហ៊ុនហៅដំណើរការដូចគ្នា កំណត់ពេលវេលាចាំ និងធ្វើឲ្យគ្រប់គ្រង(cache)សម្របសម្រួលទៅតាមប្រភេទទិន្នន័យ និងលក្ខខណ្ឌសេវាកម្ម។

បញ្ជីនៃកន្លែង និងស្ថិតិពេលពិតមិនមានតម្រូវការត្រជាក់ដូចគ្នា។ សូមផ្ទៀងផ្ទាត់ផ្លូវការដោយប្រើការឆ្លើយតបពេញលេញ, ទទេ, ផ្នែក និងកំហុស មុនពេលបង្ហាញស្វែងរកទៅអ្នកប្រើ។

ពង្រីកការស្វែងរកទៅសេវាកម្សាន្តក្នុងទីក្រុង

ចំណត និងសេវាកម្មក្នុងទីក្រុងប្រើផ្លូវផ្សេងៗគ្នា។ ដើម្បីស្វែងរកបង្គន់ជុំវិញចំណុចដូចគ្នា, ទិន្នន័យ GET /v1/services/nearby សូមបញ្ចូល lat និង lon ជាមួយ types=toilets។ កុំផ្ញើ modes=toilets ទៅផ្លូវនេះ៖ វាកម្មនេះសម្រាប់ URL របស់ផែនទី មិនមែនជាការដាក់តម្រុយសេវាកម្មទេ។

ឧទាហរណ៍ JavaScript ខាងក្រោម​បង្កើត URL សម្រាប់សេវាកម្មក្នុងកាំរសំឡេង 600 មែត្រ។ វា​មិនបង្កើតសំណើបានទេ; សូមប្រើការគ្រប់គ្រង HTTP និងកិច្ចសន្យាដដែលដែលបានរៀបរាប់ខាងលើ។ ប្រភេទមាតិកាដែលបានរំពឹងទុកឥឡូវនេះគឺ services មិនមែន stations ទេ។ រក្សា attribute service_type, location, distance_meters និង attribute ដែលមានពិតប្រាកដ។

កិច្ចសន្យា REST បានបរិយាយអំពី toilets, drinking_water, fountain, wifi, parking, charging, aed និង locker។ ប្រភេទដែលបានបង្ហាញដោយ MCP អាចខុសគ្នា។ សម្រាប់ប៉ារ៉ាមែត្រដែលទទួលបាន, កំណត់ និងកំណត់ដែនសម្រាប់ការចូលរបស់អ្នក សូមពិនិត្យវាលចំនុចនៃចំណុចប្រទាក់ដែលបានប្រើ។

អត្ថបទនៃសេវាកម្មមិនធានាថាវាបើកនៅពេលស្វែងរកទេ។ ភាពឈប់សម្រាំងមិនបានអាចមមាញឹកដូចជាសេវាកម្មមិនអាចប្រើបាន; បញ្ជីទទេដែលមានកំហុសមិនបញ្ជាក់ពីការបាត់បង់បង្គន់។ សូមរក្សាទិន្នន័យឲ្យច្បាស់លាស់សម្រាប់គ្រួសារនីមួយៗ ជៀសវាងកាត់ទ្រូងវាទៅមានតែឈ្មោះនិងចំណុចតែមួយ។

សម្រាប់ផែនទីរួម, សហការឡើងវិញលទ្ធផលជាមួយគ្រួសារនិងអត្តសញ្ញាណរបស់ពួកវា។ បង្ហាញកំហុសសេវាកម្មដោយមិនលុបចំណតដែលបានត្រឡប់ពី Transit។ ការស្វែងរកនៅតែមជ្ឈមណ្ឌលលើចំណុចដដែល ប៉ុន្តែស្ថានភាពនិងការគ្រប់គ្រងអាចខុសគ្នា។

const url = new URL('https://api.roote.ai/v1/services/nearby');
url.search = new URLSearchParams({
  lat: '44.8416106', lon: '-0.5810938',
  radius: '600', limit: '10', types: 'toilets'
}).toString();
console.log(url.toString());

វាយតម្លៃការស្វែងរកទទេឬមានកំហុស

បញ្ចូលផែនទីដែលបានតម្រូវផ្ទាល់ក្នុងគេហទំព័រ

បង្កើតជំនួយការជុំវិញការស្វែងរកទាំងនេះ

សំណួរញឹកញាប់

Nearby ផ្តល់ដំណើរការចេញបន្ទាប់មកទេ?

គ្មាននៅក្នុងកិច្ចសន្យាបច្ចុប្បន្ននេះទេ។ ផ្លូវនេះស្វែងរកកន្លែងដឹកជញ្ជូន; ដំណើរចេញទាមទារជម្លោះសមត្ថភាពផ្សេងទៀត។

អាចបង្ហាញបញ្ជីទទេបន្ទាប់ពីកំហុសមួយបានទេ?

បង្ហាញការមិនអាចប្រើបាន។ កំហុសមិនបញ្ជាក់កន្លែងខ្វះ។

អាចដាក់តោន API នៅក្នុងកម្មវិធីរកមើលទេ?

សម្ងាត់ត្រូវរក្សាទុកនៅផ្នែកម៉ាស៊ីនបម្រើ។ ប្រើម៉ូដែលចូលដែលបានរៀបចំសម្រាប់កម្មវិធី និងគណនីរបស់អ្នក។