API Block - உங்கள் சாட்பாட் ஓட்டத்திலிருந்து வெளிப்புற API களை அழைத்தல்

கண்ணோட்டம்

API Block உங்கள் சாட்பாட் உரையாடலின் நடுவில் எந்தவொரு வெளிப்புற REST API ஐயும் அழைத்து, பதிலைப் பிடித்து, வெற்றி அல்லது தோல்வியின் அடிப்படையில் ஓட்டத்தை வழியமைக்க அனுமதிக்கிறது. உங்கள் தரவுத்தளத்தில் ஆர்டர்களைத் தேட, OTP களைச் சரிபார்க்க, சரக்கு நிலையைப் பெற, கணக்கு இருப்புகளைச் சரிபார்க்க, அல்லது ஒரு HTTP எண்ட்பாயிண்டை வெளிப்படுத்தும் எந்தவொரு அமைப்பையும் ஒருங்கிணைக்க இதைப் பயன்படுத்துங்கள்.

பாட் ஒரு API block ஐ அடையும்போது, அது கட்டமைக்கப்பட்ட HTTP கோரிக்கையை அனுப்பி, பதிலுக்காக காத்திருந்து, JSON அல்லது XML body இலிருந்து புலங்களை மாறிகளாகப் பிரித்தெடுத்து, பின்னர் வெற்றி கிளை (HTTP 2xx/3xx) அல்லது தோல்வி கிளையைப் (HTTP 4xx/5xx) பின்பற்றுகிறது. ஓட்டத்தில் உள்ள அடுத்த தொகுதிகள் பிரித்தெடுக்கப்பட்ட மாறிகளை செய்திகள், நிபந்தனைகள், அல்லது அடுத்தடுத்த API அழைப்புகளில் பயன்படுத்தலாம்.

அதை எங்கே கண்டுபிடிப்பது

1. Studio இல் உங்கள் சாட்பாட்டைத் திறக்கவும்
2. இடது பக்கப்பட்டியில் இருந்து API block ஐ கேன்வாஸுக்கு இழுக்கவும்
3. அதை எந்தவொரு முந்தைய தொகுதியிலிருந்தும் இணைக்கவும்
4. அதைக் கட்டமைக்க தொகுதியை இரட்டை-கிளிக் செய்யுங்கள்

API block இல் இரண்டு வெளியீட்டு இணைப்புகள் உள்ளன: 2xx மற்றும் 3xx பதில்களுக்கான Success (மேல்/இயல்புநிலை), மற்றும் 4xx மற்றும் 5xx பதில்களுக்கான Failure (இரண்டாம்நிலை).

கட்டமைப்பு

படி 1: கோரிக்கை URL மற்றும் Method ஐ அமைக்கவும்

புலம்	விளக்கம்
URL	முழு எண்ட்பாயிண்ட், எடுத்துக்காட்டாக https://api.example.com/orders/{order_id}
Method	HTTP வினைச்சொல்: GET, POST, PUT, PATCH, அல்லது DELETE

{variable_name} தொடரியலைப் (ஒற்றை சுருள் அடைப்புக்குறிகள்) பயன்படுத்தி ஓட்டத்தில் முன்னர் பிடிக்கப்பட்ட எந்த மாறியையும் செருகலாம். கோரிக்கை அனுப்பப்படுவதற்கு முன் இயக்க நேரத்தில் மாறிகள் தீர்க்கப்படுகின்றன.

படி 2: Query Parameters ஐச் சேர்க்கவும் (விருப்பத்தேர்வு)

GET கோரிக்கைகளுக்கு, URL இல் கீ-மதிப்பு ஜோடிகளைச் சேர்க்க Query Parameters ஐப் பயன்படுத்துங்கள். ஒவ்வொரு வரிசையும் ஒரு Key மற்றும் ஒரு Value ஐ எடுக்கிறது. மாறி பதிலீடு இரண்டு புலங்களிலும் வேலை செய்கிறது.

Key: customer_email       Value: {email}
Key: include_archived     Value: false

படி 3: Headers ஐ கட்டமைக்கவும்

Headers பகுதியின் கீழ் தனிப்பயன் HTTP headers ஐச் சேர்க்கவும். ஒவ்வொரு வரிசையும் ஒரு Key மற்றும் ஒரு Value ஐ எடுக்கிறது.

Key: Content-Type         Value: application/json
Key: Accept               Value: application/json
Key: X-Custom-Header      Value: {tenant_id}

நீங்கள் ஒரு body வடிவத்தைத் தேர்ந்தெடுக்கும்போது Content-Type தானாகக் கண்டறியப்படுகிறது, ஆனால் நீங்கள் அதை மீறலாம்.

படி 4: Authentication ஐச் சேர்க்கவும்

API block மூன்று அங்கீகார முறைகளை ஆதரிக்கிறது. உங்கள் இலக்கு API உடன் பொருந்தும் ஒன்றைத் தேர்ந்தெடுக்கவும்.

Auth வகை	புலங்கள்	அது எவ்வாறு அனுப்பப்படுகிறது
Basic Auth	Username, Password	Authorization: Basic <base64> ஆக அனுப்பப்படுகிறது
Bearer Token	Bearer Token	Authorization: Bearer <token> ஆக அனுப்பப்படுகிறது
Custom Header	Header Name, Header Value	<Name>: <Value> ஆக அனுப்பப்படுகிறது (API கீ கள், தனிப்பயன் திட்டங்களுக்கு)

குறிப்பு: x-api-key அல்லது அதுபோன்றதைப் பயன்படுத்தும் API களுக்கு, Custom Header ஐத் தேர்ந்தெடுத்து Name ஐ x-api-key க்கும் Value ஐ உங்கள் கீ க்கும் அமைக்கவும். நீங்கள் கீ ஐ ஒரு மாறியில் சேமித்து அதை {api_key} ஆகவும் குறிப்பிடலாம்.

படி 5: கோரிக்கை Body ஐ உருவாக்குங்கள்

POST, PUT, மற்றும் PATCH கோரிக்கைகளுக்கு, Body பகுதியில் body ஐக் கட்டமைக்கவும். வடிவத்தைத் தேர்ந்தெடுக்கவும்:

வடிவம்	எப்போது பயன்படுத்துவது
JSON	பெரும்பாலான நவீன REST API கள்
XML	மரபு SOAP அல்லது XML எண்ட்பாயிண்ட்கள்
None	body தேவையில்லை (GET மற்றும் DELETE க்கு வழக்கமானது)

body எடிட்டரில் raw JSON அல்லது XML ஐ எழுதுங்கள். மாறிகளை இன்லைனாக செருகலாம்:

{
  "order_id": "{order_id}",
  "customer": {
    "name": "{name}",
    "email": "{email}"
  },
  "total": {amount}
}

படி 6: பதிலை மாறிகளுக்கு வரைபடமாக்குங்கள்

Save Response to Variables இன் கீழ், JSON பதிலிலிருந்து புலங்களை ஓட்ட மாறிகளாக எவ்வாறு பிரித்தெடுப்பது என்பதை வரையறுக்கவும்.

JSON Path	Variable Name
result.user.name	user_name
data.orders[0].status	order_status
items[*].id	item_ids

ஆதரிக்கப்படும் path தொடரியல்:

• உள்ளமைக்கப்பட்ட பொருள்களுக்கு Dot notation: result.user.email
• Array index: items[0].name
• Wildcard array extraction: items[*].id அனைத்து ID களையும் ஒரு வரிசையாகத் திருப்பித் தருகிறது
• Root field: status அல்லது message

பிரித்தெடுக்கப்பட்ட மதிப்புகள் அனைத்து அடுத்தடுத்த தொகுதிகளிலும் {variable_name} ஆகக் கிடைக்கின்றன.

படி 7: சமர்ப்பித்து சேமிக்கவும்

தொகுதி மோடலில் Submit ஐக் கிளிக் செய்து, பின்னர் மேல் பட்டியில் உள்ள Save Changes ஐப் பயன்படுத்தி ஓட்டத்தைச் சேமிக்கவும்.

பதில் எவ்வாறு கையாளப்படுகிறது

வெற்றி பாதை (HTTP 2xx / 3xx)

1. Save Response to Variables இலிருந்து மாறிகள் நிரப்பப்படுகின்றன
2. ஓட்டம் Success வெளியீட்டு இணைப்பைப் பின்பற்றுகிறது

தோல்வி பாதை (HTTP 4xx / 5xx)

1. பிழை body ஐப் பொறுத்து பதில் மாறிகள் நிரப்பப்படலாம் அல்லது நிரப்பப்படாமல் இருக்கலாம்
2. ஓட்டம் Failure வெளியீட்டு இணைப்பைப் பின்பற்றுகிறது
3. ஒரு நட்பான பிழை செய்தியை அனுப்ப அல்லது மீண்டும் முயற்சிக்க இந்தக் கிளையைப் பயன்படுத்துங்கள்

Timeout

கோரிக்கைகள் 30 வினாடிகளுக்குப் பிறகு நேரம் முடிந்துவிடும். உங்கள் API மெதுவாக இருந்தால், வேலையை இரண்டு படிகளாகப் பிரிப்பதை அல்லது ஒரு webhook-உந்துதலான async வடிவத்தைப் பயன்படுத்துவதைக் கருத்தில் கொள்ளுங்கள்.

API Playground இல் சோதனை

ஒவ்வொரு API block அழைப்பும் பதிவுசெய்யப்பட்டு Studio க்குள் API Playground இல் கிடைக்கிறது. ஒவ்வொரு சோதனை இயக்கத்திற்கும் நீங்கள் காணக்கூடியவை:

• முழுமையாகத் தீர்க்கப்பட்ட URL, method, மற்றும் headers
• அனுப்பப்பட்ட கோரிக்கை body
• பெறப்பட்ட HTTP நிலை குறியீடு
• முழு பதில் body
• பிரித்தெடுக்கப்பட்ட மாறிகள்

ஓட்டத்தை அனுப்புவதற்கு முன் template variables, authentication, மற்றும் JSON path mappings ஐ பிழைத்திருத்த playground ஐப் பயன்படுத்துங்கள்.

சிறந்த நடைமுறைகள்

• தொகுதி கட்டமைப்பில் அல்லாமல், மாறிகளில் ரகசியங்களைச் சேமிக்கவும். சூழல்-சார்ந்த அமைப்புகளிலிருந்து API கீ களைப் பிடித்து அவற்றை மாறிகள் வழியாகக் கடத்துங்கள், இதனால் அதே ஓட்டம் staging மற்றும் production இல் வேலை செய்கிறது
• எப்போதும் Failure கிளையை கட்டமைக்கவும். API அழைப்பு வெற்றியடைகிறது என்று ஒருபோதும் கருதாதீர்கள். "உங்கள் ஆர்டரை இப்போது மீட்டெடுக்க முடியவில்லை. தயவுசெய்து பின்னர் மீண்டும் முயற்சிக்கவும்" போன்ற ஒரு பின்னடைவு செய்தியை அனுப்பவும்.
• கோரிக்கை body களை சிறியதாக வைத்திருங்கள். API க்கு தேவைப்படாவிட்டால் முழு அரட்டை வரலாறுகள் அல்லது பெரிய பேலோடுகளை அனுப்ப வேண்டாம்
• பயன்படுத்தும் முன் பதில் புலங்களைச் சரிபார்க்கவும். order_status இல்லாமல் போகலாம் எனில், ஒரு செய்தியில் பயன்படுத்துவதற்கு முன் {order_status} ஐச் சரிபார்க்க API அழைப்புக்குப் பிறகு ஒரு Condition block ஐச் சேர்க்கவும்
• விளக்கமான மாறி பெயர்களைப் பயன்படுத்துங்கள். user_email ஆனது val1 ஐ விட சிறந்தது, ஏனெனில் Playground மற்றும் உரையாடல் பதிவில் பிழைத்திருத்துவது எளிது
• JSON ஐ அனுப்பும்போது Content-Type ஐ வெளிப்படையாக அமைக்கவும், இதனால் கடுமையான API கள் கோரிக்கையை ஏற்கின்றன

பொதுவான பயன்பாட்டு வழக்குகள்

ஆர்டர் தேடல்

வாடிக்கையாளர் ஒரு ஆர்டர் ID ஐ வழங்குகிறார், பாட் உங்கள் இ-காமர்ஸ் பின்தளத்திலிருந்து நிலையைப் பெறுகிறது.

• Method: GET
• URL: https://api.myshop.com/orders/{order_id}
• Auth: Bearer Token
• Response Map: data.status ஐ order_status க்கு, data.tracking_url ஐ tracking_url க்கு

OTP சரிபார்ப்பு

பாட் ஒரு 6-இலக்க குறியீட்டைச் சேகரித்து, உங்கள் சரிபார்ப்பு எண்ட்பாயிண்டை அழைத்து, முடிவின் அடிப்படையில் கிளைகிறது.

• Method: POST
• URL: https://api.myapp.com/verify-otp/
• Body: {"phone": "{phone}", "code": "{otp_code}"}
• Response Map: verified ஐ otp_verified க்கு
• அடுத்து ஒரு Condition block ஐப் பயன்படுத்துங்கள்: {otp_verified} == true எனில் தொடரவும், இல்லையெனில் மீண்டும் கேட்கவும்

CRM தொடர்பு ஒத்திசைவு

பயனர் தகுதியை நிறைவு செய்யும்போது சேகரிக்கப்பட்ட தொடர்பு விவரங்களை உங்கள் CRM க்குத் தள்ளுங்கள்.

• Method: POST
• URL: https://api.crm.com/v1/contacts/
• Auth: Custom Header (x-api-key: {crm_key})
• Body: {"name": "{name}", "email": "{email}", "source": "chatbot"}

சிக்கல் தீர்வு

கோரிக்கை 401 Unauthorized உடன் தோல்வியடைகிறது

1. auth வகை API எதிர்பார்ப்பதுடன் பொருந்துகிறதா என்பதைச் சரிபார்க்கவும்
2. Bearer டோக்கன்களுக்கு, டோக்கன் புலத்தில் Bearer என்ற வார்த்தையைச் சேர்க்க வேண்டாம். தொகுதி அதைத் தானாகச் சேர்க்கிறது
3. Custom Header auth க்கு, header பெயர் API ஆவணங்களுடன் சரியாகப் பொருந்துகிறதா என்பதைச் சரிபார்க்கவும் (சில API களுக்கு எழுத்து-உணர்திறன்)
4. header அனுப்பப்படுகிறதா என்பதை உறுதிப்படுத்த API Playground இல் கோரிக்கையை ஆய்வு செய்யுங்கள்

பதிலிலிருந்து மாறிகள் நிரப்பப்படவில்லை

1. API Playground ஐத் திறந்து உண்மையான பதில் body ஐ ஆய்வு செய்யுங்கள்
2. JSON path பதில் கட்டமைப்புடன் பொருந்துகிறதா என்பதை உறுதிப்படுத்தவும். Paths எழுத்து-உணர்திறன் கொண்டவை
3. வரிசைகளுக்கு, ஒற்றை மதிப்புக்கு items[0].field அல்லது அனைத்து மதிப்புகளுக்கும் items[*].field ஐப் பயன்படுத்துங்கள்
4. பதில் XML எனில், நீங்கள் body வடிவத்தைச் சரியாக அமைத்துள்ளீர்கள் என்பதை உறுதிசெய்யுங்கள். JSON paths பாகுபடுத்தப்பட்ட XML இலும் வேலை செய்கின்றன

API வேலை செய்யும்போதும் ஓட்டம் தோல்வி கிளையைப் பின்பற்றுகிறது

1. API Playground இல் HTTP நிலை குறியீட்டைச் சரிபார்க்கவும். சில API கள் POST இல் 201 (Created) ஐத் திருப்பித் தருகின்றன, இது இன்னும் வெற்றியே
2. API 200 ஐத் திருப்பித் தந்தாலும் body இல் ஒரு பிழையுடன் இருந்தால், பதில் புலத்தை ஆய்வு செய்ய வெற்றி கிளைக்குப் பிறகு ஒரு Condition block ஐப் பயன்படுத்துங்கள்

கோரிக்கை நேரம் முடிகிறது

1. timeout 30 வினாடிகளில் நிலையானது. உங்கள் API தொடர்ந்து அதிக நேரம் எடுத்தால், API நிகழ்நேர அரட்டைக்கு பொருத்தமாக இருக்காது
2. மெதுவான வேலையை ஒரு பின்னணி வேலைக்கு நகர்த்தி முடிவுக்காக போல் செய்வதைக் கருத்தில் கொள்ளுங்கள், அல்லது தயாராக இருக்கும்போது அறிவிக்கப்பட ஒரு webhook ஐப் பயன்படுத்துங்கள்

Template variables கோரிக்கையில் raw {variable} ஆகத் தோன்றுகின்றன

1. மாறி ஓட்டத்தில் முந்தைய தொகுதியால் அமைக்கப்பட்டது என்பதை உறுதிப்படுத்தவும்
2. மாறி பெயரின் எழுத்துப்பிழையைச் சரிபார்க்கவும் (எழுத்து-உணர்திறன்)
3. அந்தப் புள்ளியில் எந்த மாறிகள் உண்மையில் நிரப்பப்பட்டுள்ளன என்பதை ஆய்வு செய்ய Conversation Log ஐப் பயன்படுத்துங்கள்

அடுத்த படிகள்

• Webhook Block - ஒரு ஓட்டத்தைத் தூண்ட அல்லது மீண்டும் தொடர உள்வரும் HTTP அழைப்புகளைப் பெறவும்
• Conversation End Block - மறுதொடக்க பட்டனுடன் உரையாடல்களை முடிக்கவும்
• Studio கண்ணோட்டம் - அனைத்து தொகுதி வகைகள் மற்றும் ஓட்ட பில்டர் அம்சங்களை ஆராயுங்கள்