Ինչպես օգտագործել Webform REST մոդուլը Drupal 11-ի հետ. Գործնական ուղեցույց

Վեբ ծրագրավորման մշտապես զարգացող աշխարհում Drupal 11-ը առանձնանում է որպես ամենահզոր և ճկուն հարթակներից մեկը՝ դինամիկ կայքեր և հավելվածներ կառուցելու համար։ Դրա մոդուլային ճարտարապետությունը հնարավորություն է տալիս ծրագրավորողներին հարմարեցնել և ընդլայնել հիմնական ֆունկցիոնալությունը՝ տարբեր նախագծերի պահանջներին համապատասխան։

Նման ընդլայնումներից մեկն է Webform REST մոդուլը, որը հզոր գործիք է՝ Drupal-ը RESTful API-ների միջոցով արտաքին հավելվածների հետ ինտեգրելու համար։ Այս ուղեցույցը ներկայացնում է Webform REST մոդուլի օգտագործման գործնական ներմուծում Drupal 11-ում՝ ներկայացնելով դրա տեղադրումն ու կարգավորումը և ցույց տալով, թե ինչպես արդյունավետ կերպով աշխատել API-ի հետ։

---

Ինչ կսովորեք

Այս հոդվածում կներկայացվեն հետևյալ թեմաները․

• Webform REST մոդուլի ակնարկ

• Պահանջվող մոդուլներ և կախվածություններ

• Webform REST և REST UI մոդուլների տեղադրում

• Webform REST մոդուլի կարգավորում

• CORS-ի կարգավորում

• API հարցումներ կատարելը

• Հարցման և պատասխանի payload-ների ըմբռնում

---

Մոդուլի ակնարկ․ Webform REST

Webform REST մոդուլը ընդլայնում է Drupal-ի Webform հնարավորությունները՝ բացահայտելով ձևերի հետ կապված ֆունկցիոնալություն RESTful վերջնակետերի միջոցով։ Դրա միջոցով կարող եք կատարել գործողություններ՝ ձևերի ստեղծում, դիտում, թարմացում, ջնջում, ինչպես նաև ձևի տվյալների ներկայացում և ստացում HTTP հարցումների միջոցով։

Այս մոդուլը հատկապես օգտակար է Drupal-ը ինտեգրելու համար արտաքին հարթակների հետ, օրինակ՝

• CRM համակարգեր

• Էլ․ փոստի մարքեթինգային գործիքներ

• Բջջային հավելվածներ

• Երրորդ կողմի ծառայություններ

Այս ինտեգրումները հնարավորություն են տալիս օպտիմալացնել աշխատանքային հոսքերը և կենտրոնացնել տվյալների հավաքագրումը՝ զգալիորեն բարձրացնելով հավելվածի արդյունավետությունը։

---

Նախապայմաններ

Webform REST մոդուլից օգտվելու համար պետք է ունենաք հետևյալ մոդուլները՝

• Webform – վեբ ձևերի կառուցման և կառավարման համար

• REST UI – RESTful վերջնակետերի և թույլտվությունների կարգավորման համար

• Webform REST – հիմնական API մոդուլը

---

Webform REST և կախվածությունների տեղադրում

Այս ուղեցույցում մենք օգտագործում ենք Docker և Lando՝ լոկալ մշակման միջավայրը կառավարելու համար և Composer՝ կախվածությունները տեղադրելու համար։

Webform REST մոդուլը տեղադրելու համար օգտագործեք հետևյալ հրամանը՝

$ lando composer require 'drupal/webform_rest:^4.0'

Մոդուլը ակտիվացնելու համար՝

$ lando drush en webform_rest

Նաև ակտիվացրեք REST UI մոդուլը, որը թույլ է տալիս կարգավորել REST վերջնակետերը ադմինիստրատիվ ինտերֆեյսից՝

$ lando drush en restui

Կարող եք մոդուլները ակտիվացնել նաև ադմինիստրատիվ միջերեսից՝
/admin/modules

---

Webform REST մոդուլի կարգավորում

Պահանջվող մոդուլները ակտիվացնելուց հետո, գնացեք REST-ի կարգավորման էջ՝

Ուղի (Path): /admin/config/services/rest

Ակտիվացրեք հետևյալ REST ռեսուրսները՝

• Webform Submission

• Webform Elements

• Webform Submit

Այս ռեսուրսները տրամադրում են անհրաժեշտ վերջնակետերը ձևերի և դրանց տվյալների հետ աշխատելու համար REST-ով։

Պետք է ընտրել առնվազն մեկ վավերացման մեթոդ, օրինակ՝ "cookie":

Եթե ցանկանում եք, որ անանուն օգտվողները կարողանան հարցումներ ուղարկել վեբ-ձևին, պետք է համապատասխան թույլտվություն տալ Anonymous դերին։ Մասնավորապես, պետք է թույլատրել նրանց կատարել POST հարցումներ Webform Submit REST ռեսուրսի համար։

Այս թույլտվությունը կարելի է կարգավորել հետևյալ հասցեով՝
/admin/people/permissions

RESTful Web Services բաժնում նշեք “Access POST on Webform Submit resource” թիկնոցի վրա Anonymous user դերի համար։ Սա երաշխավորում է, որ արտաքին օգտվողներն ու համակարգերը, առանց մուտք գործելու, կարող են հաջողությամբ տվյալներ ներկայացնել ձեր Drupal կայքում Webform REST API-ով։

Մի քանի խոսք CORS-ի մասին

Եթե պատրաստվում եք հարցումներ ուղարկել այլ տիրույթից, ապա հավանաբար կբախվեք CORS խնդիրների՝ օրինակ այսպիսի սխալի՝

CORS-ի ըմբռնում և կարգավորում Drupal 11-ում

CORS (Cross-Origin Resource Sharing) վեբ զննարկիչների կողմից ներդրված անվտանգության մեխանիզմ է, որը կառավարում է, թե ինչպես են ռեսուրսները հասանելի տարբեր ծագումներից (origin)։ Origin-ը համակցված է տիրույթի անուն, պրոտոկոլ և պորտ։

Պարզ ասած, CORS-ը թույլ է տալիս սերվերին նշել, թե որ արտաքին տիրույթներն են կարող օգտվել որոշակի ռեսուրսներից։ Եթե CORS-ը ճիշտ չի կարգավորվել, զննարկիչները կիրառում են Same-Origin Policy (նույն տիրույթի քաղաքականություն), որը արգելափակում է արտատարածքային հարցումները։

---

CORS-ի կարգավորում Drupal 11-ում

Drupal 11-ում CORS-ի կարգավորումները կատարվում են services.yml ֆայլի cors.config բաժնում։ Լռելյայն այս կարգավորումը անջատված է, այսինքն՝ բոլոր cross-origin հարցումները կարգելափակվեն, եթե հատուկ չթույլատրեք։

Արտաքին հաճախորդների համար CORS-ը միացնելու համար (օրինակ՝ JavaScript frontend, բջջային հավելված) պետք է փոխել services.yml ֆայլը, օրինակ՝ զարգացման/փորձարկման համար կարող եք օգտագործել այսպիսի թույլատրող կարգավորում՝

cors.config:
    enabled: true
    allowedHeaders: ['x-csrf-token','authorization','content-type','accept','origin','x-requested-with', 'access-control-allow-origin','x-allowed-header','*']
    allowedMethods: ['*']
    allowedOrigins: ['*']
    exposedHeaders: false
    maxAge: false
    supportsCredentials: true

services.local.yml ֆայլի կարգավորումը լոկալ միջավայրում

Drupal-ի լոկալ զարգացման միջավայրերում սովորաբար կա services.local.yml ֆայլ։ Այս ֆայլը նախատեսված է services.yml-ի կարգավորումները վերագրանցելու համար։ Հետևաբար, եթե services.yml-ում փոփոխություններ եք կատարում, բայց services.local.yml-ում կան հակասական կամ թերի կարգավորումներ, ապա հիմնականը չի գործի։

Համոզվեք, որ CORS-ի կարգավորումները պատշաճ արտացոլված են նաև services.local.yml-ում։

Կեշը մաքրեք կարգավորումից հետո

YAML ֆայլերը թարմացնելուց հետո անպայման մաքրեք Drupal-ի կեշը, որպեսզի փոփոխությունները ուժի մեջ մտնեն․

$ lando drush cr

Ուշադրություն՝ YAML-ի ներսծուծման (indentation) վրա

Հատկապես ուշադրություն դարձրեք YAML-ի ներսծուծմանը (indentation)․ անգամ մեկ ավել կամ պակաս բացատը կարող է դառնալ խնդիր և հանգեցնել, որ կարգավորումները չգործեն։ Եթե փոփոխությունը ուժի մեջ չի մտնում, նախ ստուգեք ներսծուծումը։

---

Webform REST մոդուլի կիրառումը

Կարգավորումներն ավարտելուց հետո կարող եք սկսել REST-ով ձևեր ներկայացնել։ Այս գործընթացը ներառում է POST հարցում Webform REST վերջնակետին՝ անհրաժեշտ վերնագրերով և տվյալներով։

Վերջնակետ

POST /webform_rest/submit

Պահանջվող Header

Content-Type: application/json

Օրինակ․ Axios-ով ձևի ներկայացում

Սա Axios-ով form data ներկայացնելու օրինակ JavaScript-ում՝

 const response = await axios.post('http://yoursite.lndo.site/webform_rest/submit', {
    "webform_id": "some_rest_form",
    "name": "Ivan Abramenko",
    "email": "levmyshkin89@gmail.com",
  }, {
    headers: {
    "Content-Type": 'application/json',
    },
  });

Օրինակը ցույց է տալիս ինչպես կատարել POST հարցում Axios-ով, բայց կարող եք օգտագործել ցանկացած այլ HTTP գրադարան կամ ֆրեյմվորե։

Հարցման payload-ը հիմնականում բաղկացած է webform_id-ից (ձևի մեքենայական անունը) և դաշտերից։

{
   "webform_id": "some_rest_form",
   "name": "Ivan Abramenko",
   "email": "levmyshkin89@gmail.com"
}

Հաջող ներկայացման պատասխանի payload-ը պարունակում է հետևյալ դաշտերը․

• sid – ներկայացման եզակի նույնացուցիչ
• confirmation_url – հաստատման հղում
• confirmation_message – հաստատման հաղորդագրություն
• confirmation_title – հաստատման վերնագիր

{
   "sid": "ae8c3bd4-91a2-5c17-a264-59c86157457b",
   "confirmation_type": "inline",
   "confirmation_url": "",
   "confirmation_message": "Just a confirmation message",
   "confirmation_title": "A confirmation title"
}

Բացի դրանից, Webform-ը նաև վերադարձնում է վավերացման սխալների մասին հաղորդագրություններ։ Օրինակ, եթե պարտադիր դաշտը չես լրացրել, կստանաք նման պատասխան․

{
   "message": "Submitted Data contains validation errors.",
   "error": {
       "email": "The email field is mandatory."
   }
}

API պատասխանի մշակումը

API-ի պատասխան տվյալների հիման վրա կարող եք ծրագրային կերպով օգտվողին ներկայացնել հաջողության հաղորդագրություն, վավերացման սխալներ կամ ներկայացման ձախողման մասին տվյալներ։ Պատասխանների ճիշտ մշակումը բարձրացնում է օգտագործողի փորձը։

Անկախ նրանից՝ ինտեգրում եք ձևը frontend ֆրեյմվորեի, թե բջջային հավելվածի հետ, API-ի պատասխանի կառավարումը կարևոր է հարմար և ինտուիտիվ փորձ ապահովելու համար։

---

Ամփոփում

Webform REST մոդուլը Drupal 11-ի համար հզոր և ճկուն լուծում է վեբ-ձևերի հետ աշխատելու համար RESTful API-ների միջոցով։ Արտաքին հավելվածներին հնարավորություն տալով ներկայացնել և փոխել ձևի տվյալները՝ այն էապես ընդլայնում է Drupal-ի ինտեգրման հնարավորությունները՝ իդեալական դարձնելով այն ժամանակակից decoupled կամ headless ճարտարապետությունների համար։

Այս հոդվածում դիտարկեցինք՝

• Webform REST մոդուլի ներածություն

• Քայլ առ քայլ տեղադրում և կարգավորում

• Ինչպես ներկայացնել տվյալներ API-ով (գործնական օրինակ)

Թեև այս ուղեցույցը կենտրոնացած էր ձևի ներկայացման վրա, Webform REST մոդուլը աջակցում է նաև՝

• PATCH հարցումներ՝ ներկայացումների թարմացման համար

• GET հարցումներ՝ ներկայացումների կամ դաշտերի ստացման համար

• Վավերացման և մատչելիության լրացուցիչ կարգավորումներ

Այս առաջադեմ գործարկումները կներկայացվեն հաջորդ դասընթացներում։