Povezava spletnega mesta z API-jem

API CMS omogoča, da vaše spletno mesto pridobi in upodobi objavljeno vsebino iz Profound CMS. Uporabite ga lahko za poganjanje strani z dokumentacijo, marketinških strani, blogov, centrov za pomoč ali katere koli druge izkušnje, ki so usmerjene v vsebino.

Običajna integracija ima tri dele:

1. Konfigurirajte povezavo s sistemom CMS
2. Pridobite objavljeno vsebino
3. Upodobite vsebino v svoji aplikaciji

Konfiguracija

Če želite svojo aplikacijo povezati s sistemom CMS, navedite URL API-ja CMS, identifikator spletnega mesta in ključ API.

const cmsConfig = {
  cmsUrl: 'https://cms.dev.tryprofoun.com',
  websiteId: 'your-website-id',
  apiKey: process.env.PROFOUND_API_KEY,
};

Za vrednosti, ki se razlikujejo med okolji, uporabite okoljske spremenljivke:

NEXT_PUBLIC_CMS_API_URL=https://cms.dev.tryprofound.com
NEXT_PUBLIC_WEBSITE_ID=your-website-id
PROFOUND_API_KEY=your-api-key

Zasebnih ključev API ne izpostavljajte v odjemalski kodi. Ključi API naj bodo uporabljeni na vašem strežniku, v postopku gradnje ali v zalednih poteh.

Pridobivanje vsebine

Vsebina v sistemu CMS je organizirana po shemah. Na primer, vaš projekt lahko vsebuje sheme, kot so post, category, page ali section.

Za pridobivanje vsebine uporabite ime sheme:

const posts = await cms.schema('post').fetchAll();

Za pridobitev posameznega dokumenta po ID-ju:

const post = await cms.schema('post').fetchSingleById('document-id');

Če želite pridobiti lokalizirano vsebino, zahtevajte prevedeno različico sheme:

const frenchPost = await cms
  .schema('post')
  .translation('fr')
  .fetchSingleById('document-id');

Upodabljanje poti

Za spletna mesta, ki uporabljajo strani, upravljane s CMS, lahko pridobite vsebino na podlagi trenutne poti URL.

const route = await cms.route.getByPath({
  websiteId: 'your-website-id',
  path: '/docs/getting-started',
});

Odziv poti določi stran in bloke, ki jih je treba upodobiti. Vaša aplikacija lahko nato pridobi bloke in jih upodobi z vašimi komponentami.

const blocks = await cms.block.getByIds({
  websiteId: 'your-website-id',
  ids: route.blockIds,
});

Primer: upodobitev strani z dokumentacijo

async function getDocsPage(path: string) {
  const route = await cms.route.getByPath({
    websiteId: process.env.WEBSITE_ID,
    path,
  });

  const blocks = await cms.block.getByIds({
    websiteId: process.env.WEBSITE_ID,
    ids: route.blockIds,
  });

  return {
    title: route.label,
    path: route.path,
    blocks,
  };
}

Vrnjene bloke lahko uporabite za upodobitev strani z uporabo komponentnega sistema vaše aplikacije.

Predpomnjenje

Objavljeno vsebino CMS je varno predpomniti. Za večino spletnih mest predpomnite odzive API za kratek čas in jih ponovno potrdite, ko se vsebina spremeni.

Pogosta nastavitev je:

const content = await cache(
  () => cms.schema('post').fetchAll(),
  {
    revalidate: 60,
    tags: ['cms-posts'],
  }
);

Priporočeno vedenje predpomnilnika:

• Predpomnite objavljena branja.
• Za pogosto posodobljeno vsebino uporabljajte krajša okna predpomnilnika.
• Uporabljajte oznake predpomnilnika, če vaše ogrodje podpira razveljavitev na zahtevo.
• Izogibajte se predpomnjenju predogledne ali osnutne vsebine.

Način predogleda

Način predogleda omogoča urednikom, da si ogledajo neobjavljene spremembe, preden so objavljene.

Pogost vzorec je uporaba ločene poti predogleda, na primer:

/docs/getting-started
/cms-preview/docs/getting-started

Proizvodne strani naj pridobijo le objavljeno vsebino. Strani predogleda lahko sprejmejo parametre predogleda, kot so:

?edit_mode=true

Poti predogleda naj bodo običajno dinamične in naj ne bodo statično predpomnjene.

Obvladovanje napak

Vsebina CMS je med gradnjo ali zahtevkom lahko nedostopna. Vaša aplikacija naj se s tem spopade na eleganten način.

Priporočeno vedenje:

• Vrnite 404, kadar pot ne obstaja.
• Vrnite prazen seznam, kadar izbirne navigacijske vsebine ni mogoče naložiti.
• Zabeležite napake pri pridobivanju na strežniški strani.
• Izogibajte se razkrivanju notranjih napak API obiskovalcem.

Primer:

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Failed to fetch CMS post', error);
    return null;
  }
}

Varnost

Ključe API hranite zasebno in jih uporabljajte le na strežniku. Zasebnih poverilnic ne vključujte v paketke brskalnika ali javni JavaScript.

Javne okoljske spremenljivke uporabite le za vrednosti, ki niso občutljive, na primer:

• Javni URL CMS
• ID spletnega mesta
• Konfiguracija jezika

Zasebne okoljske spremenljivke uporabite za:

• Ključe API
• žetone za predogled
• skrbniške poverilnice
• skrivnosti za uvedbo

Povzetek

Uporabite API CMS, ko vaše spletno mesto potrebuje pridobivanje strukturirane vsebine, upodabljanje poti, ki jih upravlja CMS, ali podporo delovnim tokovom predogleda za urednike.

Standardna integracija naj:

• Konfigurira URL CMS, ID spletnega mesta in ključ API.
• Pridobi dokumente po shemi.
• Pridobi strani po poti.
• Upodobi bloke CMS z vašimi komponentami.
• Predpomni objavljeno vsebino.
• Ohrani predogledno vsebino dinamično.
• Hrani zasebne poverilnice na strežniku.