Ներառում է

Կարճ տարբերակ (TL;DR)՝ Օգտագործեք հարցման տող, օրինակ՝ ?include=field_comments.uid, որպեսզի ընդգրկվեն field_comments-ով հղված բոլոր էակները, ինչպես նաև uid-ով հղված բոլոր էակները այդ էակների համար։

JSON:API-ն օգնում է նվազեցնել HTTP հարցումների քանակը՝ թույլ տալով նշել կապի դաշտերի ճանապարհները, որոնք ցանկանում եք ներառել պատասխանի փաստաթղթում: Ինչպե՞ս։

Մեկ ռեսուրսի ստացում

Հոդվածի ստացում

Պատկերացրեք, որ ունեք հոդված երկու մեկնաբանությամբ, և այդ մեկնաբանություններից յուրաքանչյուրն ունի նույն հեղինակը։ Այս բոլոր տվյալները առանց ներառումների ստանալու համար նախ հարցում եք կատարում GET /jsonapi/node/article/some-random-uuid հասցեով՝

{
  "data": {
    "type": "node--article",
    "id": "some-random-uuid",
    "relationships": {
      "field_comments": {
        "links": {
          "related": {
            "href": "https://my.example.com/node/article/some-random-uuid/field_comments"
          }
        }
      }
    }
  }
}

Մեկնաբանության ստացում

Այնուհետև հարցում եք կատարում GET /node/article/some-random-uuid/field_comments հասցեով՝

{
  "data": [{
    "type": "comment",
    "id": "one-random-uuid",
    "relationships": {
      "uid": {
        "links": {
          "related": {
            "href": "https://my.example.com/comment/one-random-uuid/uid"
          }
        }
      }
    }
  }, {
    "type": "comment",
    "id": "two-random-uuid",
    "relationships": {
      "uid": {
        "links": {
          "related": {
            "href": "https://my.example.com/comment/two-random-uuid/uid"
          }
        }
      }
    }
  }
}

Օգտատերերի ստացում

Այդուհետ պետք է ևս երկու հարցում կատարեք՝ /comment/one-random-uuid/uid և /comment/two-random-uuid/uid հասցեներով։ Կարելի է տեսնել, որ երկրորդ հարցումը լրիվ ավելորդ է, քանի որ օրինակով գիտենք՝ երկու մեկնաբանության հեղինակը նույնն է։

Ուրեմն, ինչպես կարող են օգնել ներառումները (includes)?

Բոլոր տվյալների մեկ հարցմամբ ստացում՝ include-ի միջոցով

Շատ հեշտ է։ Պարզապես ավելացրեք հարցման պարամետր հիմնական հարցման հասցեին՝ այն կապի դաշտերի անուններով, որոնք ցանկանում եք ներառել, և սերվերը կհավաքի ու կավելացնի այդ բոլոր տվյալները պատասխանի փաստաթղթում։

Մեր օրինակում, պետք է հարցում անել այսպես՝ GET /jsonapi/node/article/some-random-uuid?include=field_comments.uid։ Այլ կերպ ասած, դուք ասում եք՝ «Խնդրում եմ, ավելացրեք ռեսուրսի օբյեկտները հոդվածի field_comments դաշտի համար, և հետո՝ նաև այն մեկնաբանությունների uid դաշտի համար, որոնք կան։» Այս «կապի ճանապարհները» կարող են լինել որքան ուզեք՝ սահմանափակում չկա։

Սերվերից ստացված պատասխանը կարող է լինել այսպիսի՝

{
  "data": {
    "type": "node--article",
    "id": "some-random-uuid",
    "relationships": {
      "field_comments": {
        "data": [{
          "type": "comment",
          "id": "one-random-uuid",
        }, {
          "type": "comment",
          "id": "two-random-uuid",
        }],
        "links": {
          "related": {
            "href": "https://my.example.com/node/article/some-random-uuid/field_comments"
          }
        }
      }
    }
  },
  "included": [{
    "type": "comment",
    "id": "one-random-uuid",
    "relationships": {
      "uid": {
        "data": [{
          "type": "user",
          "id": "another-random-uuid",
        }],
        "links": {
          "related": {
            "href": "https://my.example.com/comment/one-random-uuid/uid"
          }
        }
      }
    }
  }, {
    "type": "comment",
    "id": "another-random-uuid",
    "relationships": {
      "uid": {
        "data": [{
          "type": "user",
          "id": "one-random-uuid",
        }],
        "links": {
          "related": {
            "href": "https://my.example.com/comment/two-random-uuid/uid"
          }
        }
      }
    }
  }, {
    "type": "user",
    "id": "another-random-uuid",
    "attributes": {
      "name": "c0wb0yC0d3r"
    }
  }]
}

Զվարճալի չէ՞։ Միայն մեկ հարցմամբ ստացանք բոլոր տվյալները։ Նկատեք, որ օգտատիրոջ ռեսուրսի օբյեկտը ներառված է միայն մեկ անգամ, թեև երկու անգամ է հղվում։ Սա փոքր է պահում պատասխանի չափը։ Նաև, յուրաքանչյուր կապի օբյեկտում կա data բանալի։ Դա թույլ է տալիս համադրել ներառված ռեսուրսների օբյեկտները՝ ըստ նրանց հղումների։

Ե՞րբ օգտագործել include

Խոսելով պատասխանի չափի մասին... այս օրինակով, մենք ժամանակ խնայեցինք՝ բոլոր ռեսուրսները մեկ հարցմամբ ստանալով։ Բայց որոշ դեպքերում՝ հարակից ռեսուրսների ներառումը կարող է զգալիորեն մեծացնել պատասխանի չափը և/կամ դանդաղեցնել առաջին բայթի ժամանումը։ Այդ դեպքերում, ավելի լավ է զուգահեռ կատարել մի քանի հարցում։

Include՝ հավաքածուների և կապերի համար

Վերջապես, include հարցման պարամետրը աջակցվում է նաև հավաքածուի և կապի ռեսուրսների համար։ Հավաքածուների include-ը կարող է խնայել շատ ավել հարցումներ։

Include՝ հավաքածուի օրինակով

Հավաքածուի ներառումների հարցումը կարող է լինել այսպես՝ GET /jsonapi/node/article?include=uid։ included-ը նույնպես առանձնացված է data-ից (զանգված, ոչ թե օբյեկտ), ինչպես ցույց է տրված ներքևում։

{
  "data": [{...}]
  "included": [{
    "type": "user",
    "id": "another-random-uuid",
    "attributes": {
      "name": "c0wb0yC0d3r"
    }
  }]
}

Հոդվածը վերցված է Drupal փաստաթղթերից։