ساخت API با عملکردهای گتسبی – مجله سر و صدا

خلاصه سریع

در این آموزش ، پل اسکنلون نحوه ایجاد API با استفاده از توابع Gatsby و مواردی را که هنگام استقرار آن در Gatsby Cloud باید به آن توجه داشته باشید توضیح می دهد.

احتمالاً در مورد عملکردهای بدون سرور شنیده اید ، اما اگر نشنیده اید ، عملکردهای بدون سرور عملکردهایی را ارائه می دهند که معمولاً با فناوری های سمت سرور مرتبط است و می تواند در کنار کد پیش فرض بدون گرفتار شدن در زیرساخت های سمت سرور پیاده سازی شود.

با وجود کد سمت سرور و کلاینت در یک پایگاه کد ، توسعه دهندگان اصلی مانند من می توانند با استفاده از ابزارهایی که قبلاً می شناسند و دوست دارند ، دسترسی به آنچه ممکن است را افزایش دهند.

محدودیت ها

همزیستی عالی است اما حداقل دو سناریو وجود دارد که من با آنها روبرو شده ام که استفاده از توابع بدون سرور به این روش کاملاً مناسب کار مورد نظر نبود. آنها به شرح زیر است:

1. قسمت جلویی نمی تواند از عملکردهای بدون سرور پشتیبانی کند.
2. عملکرد مشابهی توسط بیش از یک قسمت جلو مورد نیاز بود.

برای کمک به ارائه زمینه ، در اینجا یک مثال از هر دو نقطه 1 و 2 که در بالا ذکر شده است ، آورده شده است. من یک پروژه منبع باز به نام MDX Embed، از سایت docs خواهید دید که وب سایت گتسبی نیست. با استفاده از آن ساخته شده است کتاب داستان و Storybook به تنهایی هیچ قابلیت عملکرد بدون سرور را ارائه نمی دهد. من می خواستم برای کمک به تامین مالی این پروژه ، مشارکت “آنچه می خواهید بپردازید” را اجرا کنم و می خواستم از Stripe برای فعال کردن پرداخت های مطمئن استفاده کنم ، اما بدون “پشتوانه” امن این امکان پذیر نبود.

با انتزاع این قابلیت در API ساخته شده با عملکردهای گتسبی ، من توانستم به خواسته خود با MDX Embed دست یابم و همچنین از همان عملکرد مجدد استفاده کنم و عملکرد “پرداخت آنچه می خواهید” را برای آن فعال کنید وبلاگ منبه

می توانید در مورد نحوه انجام این کار در اینجا بیشتر بخوانید: از نرم افزار منبع باز با عملکرد Gatsby And Stripe کسب درآمد کنید.

در این مرحله است که استفاده از توابع گتسبی می تواند به نوعی عمل کند عقب عقب برای قسمت انتهایی یا BFF 😊 و توسعه به این طریق بیشتر شبیه توسعه API است (رابط برنامه نویسی برنامه)

API ها توسط کد پیش فرض برای رسیدگی به مواردی مانند ، ورود به سیستم ، واکشی اطلاعات در زمان واقعی یا کارهای ایمن که تنها توسط مرورگر به درستی انجام نمی شوند ، استفاده می شود. در این آموزش ، نحوه ساختن API با استفاده از توابع Gatsby و استقرار آن در Gatsby Cloud را توضیح خواهم داد.

چک های قبل از پرواز

عملکردهای Gatsby هنگامی که در Gatsby Cloud یا Netlify مستقر می شوند کار می کنند ، و در این آموزش ، نحوه استقرار در Gatsby Cloud را توضیح خواهم داد ، بنابراین شما باید ثبت نام و ابتدا یک حساب کاربری رایگان ایجاد کنید.

شما همچنین نیاز به یک حساب GitHub ، GitLab یا BitBucket دارید ، اینگونه است که Gatsby Cloud کد شما را می خواند و سپس “سایت” شما یا در این مورد ، API را می سازد.

برای اهداف این آموزش ، من از GitHub استفاده می کنم. اگر ترجیح می دهید جلوتر بپرید ، کد API نسخه ی نمایشی را می توان در GitHub من پیدا کردبه

شروع شدن

یک dir جدید در جایی درایو محلی خود ایجاد کنید و موارد زیر را در ترمینال خود اجرا کنید. با این کار پیش فرض تنظیم می شود package.jsonبه

npm init -y

وابستگی ها

موارد زیر را در ترمینال خود وارد کنید تا وابستگی های مورد نیاز را نصب کنید.

npm install gatsby react react-dom

صفحات

به احتمال زیاد API شما هیچ صفحه ای نخواهد داشت ، اما از دیدن پیش فرض Gatsby خودداری کنید هشدار صفحه از دست رفته وقتی از آدرس اصلی مرورگر دیدن می کنید ، موارد زیر را به هر دو اضافه کنید src/pages/index.js و src/pages/404.jsبه

//src/pages/index.js & src/pages/404.js

export default () => null;

API

موارد زیر را به src/api/my-first-function.jsبه

کمی بعد توضیح می دهم که چه چیزی 'Access-Control-Allow-Origin', '*' این بدان معناست که ، اما به طور خلاصه ، مطمئن می شود که API های شما از مبدأ دیگر مسدود نشده اند CORSبه

//src/api/my-first-function.js

export default function handler(req, res) {
  res.setHeader('Access-Control-Allow-Origin', '*');

  res.status(200).json({ message: 'A ok!' });
}

اسکریپت ها

موارد زیر را به package.jsonبه

//package.json

...
  "scripts": {
    "develop": "gatsby develop",
    "build": "gatsby build"
  },
...

سرور توسعه گتسبی را راه اندازی کنید

برای چرخاندن سرور توسعه گتسبی موارد زیر را در ترمینال خود اجرا کنید.

npm run develop

از مرورگر درخواست دهید

با فعال بودن سرور توسعه گتسبی ، می توانید از آن دیدن کنید http: // localhost: 8000/api/my-first-function، و از آنجا که این ساده است GET درخواست شما باید موارد زیر را در مرورگر خود مشاهده کنید.

{
  "message": "A ok!"
}

تبریک میگم

شما به تازگی یک API با استفاده از توابع Gatsby ایجاد کرده اید.

استقرار

اگر پاسخ فوق را در مرورگر خود مشاهده می کنید ، می توانید فرض کنید عملکرد شما به صورت محلی کار می کند ، در مراحل زیر نحوه استقرار API خود را در Gatsby Cloud و دسترسی به آن با استفاده از HTTP درخواست از CodeSandbox

Push Code To Git

قبل از اقدام به استقرار در Gatsby Cloud ، باید کد خود را به ارائه دهنده Git مورد نظر خود هدایت کرده باشید.

ابر گتسبی

وارد حساب Gatsby Cloud خود شوید و دکمه بزرگ بنفش رنگی را که روی آن نوشته شده است “Add site +” را جستجو کنید.

در مرحله بعد ، از شما خواسته می شود که از مخزن Git وارد کنید یا از یک الگو شروع کنید ، را انتخاب کنید Import from Git Repository و ضربه بزنید nextبه

همانطور که در بالا ذکر شد Gatsby Cloud می تواند به GitHub ، GitLab یا Bitbucket متصل شود. ارائه دهنده Git مورد نظر خود را انتخاب کرده و ضربه بزنید nextبه

با اتصال ارائه دهنده Git خود ، می توانید مخزن خود را جستجو کرده و نامی برای سایت خود قائل شوید.

پس از انتخاب مخزن خود و نامگذاری سایت خود به عنوان hit nextبه

می توانید “Integrations” و “Setup” را رد کنید زیرا به این موارد نیاز نخواهیم داشت.

اگر همه چیز برای برنامه ریزی پیش رفته است ، باید چیزی شبیه به تصویر زیر را ببینید.

در بالای صفحه در سمت چپ صفحه ، نشانی اینترنتی را مشاهده می کنید که به آن ختم می شود gatsbyjs.io، این آدرس URL API شما خواهد بود و با افزودن به همه توابع ایجاد شده می توانید دسترسی پیدا کنید /api/name-of-function تا انتهای این نشانی اینترنتی

به عنوان مثال ، نسخه کامل مستقر شده از my-first-function.js برای API نسخه ی نمایشی من به شرح زیر است:

API نسخه ی نمایشی: اولین عملکرد منبه

آزمایش API شما

بازدید از URL API شما یک چیز است اما در واقع نحوه استفاده از API ها به طور معمول اینطور نیست. در حالت ایده آل برای آزمایش API خود باید از تابع کاملاً نامربوط درخواست کنید.

اینجا کجاست res.setHeader('Access-Control-Allow-Origin', '*'); به نجات می آید در حالی که همیشه مطلوب نیست که اجازه دهیم هر دامنه (وب سایت) به توابع شما دسترسی داشته باشد ، اما در بیشتر موارد ، توابع عمومی فقط همان هستند ، عمومی. تنظیم سرصفحه کنترل دسترسی روی مقدار * به این معنی که هر دامنه ای می تواند به عملکرد شما دسترسی داشته باشد ، بدون این ، هر دامنه ای غیر از دامنه ای که API در آن میزبانی شده است توسط CORS مسدود می شود.

در اینجا یک CodeSandbox است که از آن استفاده می کند my-first-function از API نسخه ی نمایشی من. برای آزمایش عملکرد خود می توانید این را فورک کرده و آدرس درخواست Axios را تغییر دهید.

CodeSandbox: اولین عملکرد من

گرفتن فانتزی

ارسال پاسخی از API شما که می گوید message: "A ok!" دقیقاً هیجان انگیز نیست ، بنابراین در بیت بعدی به شما نحوه پرس و جو را نشان می دهم GitHub REST API و با استفاده از API ای که ایجاد کرده اید یک کارت نمایه شخصی ایجاد کنید تا در سایت خود نمایش داده شود و کمی شبیه این خواهد بود.

CodeSandbox: کارت نمایه نمایشی

وابستگی ها

برای استفاده از GitHub REST API باید نصب کنید @octokit/استراحت بسته

npm install @octokit/rest

GitHub User Raw را دریافت کنید

موارد زیر را به src/api/get-github-user-raw.jsبه

// src/api/get-github-user-raw.js

import { Octokit } from '@octokit/rest';

const octokit = new Octokit({
  auth: process.env.OCTOKIT_PERSONAL_ACCESS_TOKEN
});

export default async function handler(req, res) {
  res.setHeader('Access-Control-Allow-Origin', '*');

  try {
    const { data } = await octokit.request(`GET /users/{username}`, {
      username: 'PaulieScanlon'
    });

    res.status(200).json({ message: 'A ok!', user: data });
  } catch (error) {
    res.status(500).json({ message: 'Error!' });
  }
}

نشانه دسترسی

برای برقراری ارتباط با GitHub REST API به یک رمز دسترسی نیاز دارید. با دنبال کردن مراحل این راهنمای GitHub می توانید این را دریافت کنید: ایجاد یک رمز دسترسی شخصیبه

.env متغیرها

برای ایمن نگه داشتن رمز دسترسی خود موارد زیر را به آن اضافه کنید .env.development و .env.productionبه

OCTOKIT_PERSONAL_ACCESS_TOKEN=123YourAccessTokenABC

در این راهنمای گتسبی می توانید در مورد متغیرهای محیط گتسبی بیشتر بخوانید: متغیرهای محیطیبه

شروع به توسعه سرور

همانطور که قبل از شروع سرور توسعه گتسبی با تایپ موارد زیر در ترمینال خود اقدام کرده اید.

npm run develop

از مرورگر درخواست دهید

با فعال بودن سرور توسعه گتسبی ، می توانید از آن دیدن کنید http: // localhost: 8000/api/get-github-user-raw، و از آنجا که این نیز ساده است GET درخواست شما باید موارد زیر را در مرورگر خود مشاهده کنید. (من بخشی از پاسخ را برای اختصار حذف کردم.)

{
  "message": "A ok!",
  "user": {
    "login": "PaulieScanlon",
    "id": 1465706,
    "node_id": "MDQ6VXNlcjE0NjU3MDY=",
    "avatar_url": "https://avatars.githubusercontent.com/u/1465706?v=4",
    "gravatar_id": "",
    "url": "https://api.github.com/users/PaulieScanlon",
    "type": "User",
    "site_admin": false,
    "name": "Paul Scanlon",
    "company": "Paulie Scanlon Ltd.",
    "blog": "https://www.paulie.dev",
    "location": "Worthing",
    "email": "pauliescanlon@gmail.com",
    "hireable": true,
    "bio": "Jamstack Developer / Technical Content Writer (freelance)",
    "twitter_username": "pauliescanlon",
    "created_at": "2012-02-23T13:43:26Z",
    "two_factor_authentication": true,
    ...
  }
}

در اینجا یک نمونه CodeSandbox از پاسخ کامل خام آورده شده است.

CodeSandbox: پاسخ خام

در بالا مشاهده خواهید کرد که داده های بسیار زیادی برگشت داده شده است که من واقعاً به آنها احتیاج ندارم ، این بیت بعدی کاملاً به شما بستگی دارد زیرا API شما است ، اما من دستکاری کمی در پاسخ GitHub API مفید است. قبل از ارسال مجدد آن به کد اصلی من

اگر می خواهید همین کار را انجام دهید ، می توانید یک تابع جدید ایجاد کرده و موارد زیر را به آن اضافه کنید src/api/get-github-user.jsبه

// src/api/get-github-user.js

import { Octokit } from '@octokit/rest';

const octokit = new Octokit({
  auth: process.env.OCTOKIT_PERSONAL_ACCESS_TOKEN
});

export default async function handler(req, res) {
  res.setHeader('Access-Control-Allow-Origin', '*');

  try {
    const { data } = await octokit.request(`GET /users/{username}`, {
      username: 'PaulieScanlon'
    });

    res.status(200).json({
      message: 'A ok!',
      user: {
        name: data.name,
        blog_url: data.blog,
        bio: data.bio,
        photo: data.avatar_url,
        githubUsername: `@${data.login}`,
        githubUrl: data.html_url,
        twitterUsername: `@${data.twitter_username}`,
        twitterUrl: `https://twitter.com/${data.twitter_username}`
      }
    });
  } catch (error) {
    res.status(500).json({ message: 'Error!' });
  }
}

در بالا مشاهده خواهید کرد که به جای بازگشت شیء داده کامل توسط GitHub REST API ، من فقط بیت های مورد نیاز خود را انتخاب می کنم ، نام آنها را تغییر می دهم و چند بیت قبل از نام کاربری و مقادیر URL اضافه می کنم. هنگامی که می خواهید داده ها را در کد پیش نمایش ارائه دهید ، زندگی را کمی ساده تر می کند.

در اینجا یک نمونه CodeSandbox از پاسخ فرمت شده است.

CodeSandbox: پاسخ قالب بندی شده

این بسیار شبیه به Profile Card CodeSandbox قبلی است ، اما من داده ها را نیز چاپ کرده ام ، بنابراین می توانید نحوه استفاده از هر مورد داده دستکاری شده را مشاهده کنید.

در این مرحله شایان ذکر است که هر چهار نسخه ی نمایشی CodeSandbox در این آموزش از API نسخه ی نمایشی استفاده می کنند و هیچکدام از آنها با استفاده از Gatsby ساخته نشده و یا بر روی Gatsby Cloud میزبانی نشده است – cool ay!

.env متغیرها در ابر گتسبی

قبل از استقرار دو عملکرد جدید ، باید رمز دسترسی GitHub را به بخش متغیرهای محیط در Gatsby Cloud اضافه کنید.

از کجا به کجا برویم؟

من این سوال را از خودم پرسیدم. به طور معمول از توابع بدون سرور در درخواست های سمت کلاینت استفاده می شود و در حالی که خوب است من می پرسیدم آیا می توان آنها را در زمان ساخت برای “پخت” آماری داده ها در صفحه به جای تکیه بر جاوا اسکریپت که ممکن است در کاربر غیرفعال باشد یا نشود ، استفاده کند. مرورگر

… بنابراین این دقیقاً همان کاری است که من انجام دادم.

در اینجا نوعی داشبورد داده وجود دارد که از داده های برگشتی توسط عملکردهای گتسبی در زمان اجرا و ساخت استفاده می کند. من این سایت را با استفاده از آسترو و آن را مستقر کرد صفحات GitHubبه

دلیل اینکه من فکر می کنم این یک رویکرد عالی است این است که من می توانم از عملکرد یکسانی در سرور و مرورگر بدون تکرار هر چیزی دوباره استفاده کنم.

در این Astro build من به همان نقطه پایانی که توسط API من نمایان شده است ضربه می زنم تا داده هایی را که در صفحه پخته می شوند (برای SEO عالی است) یا در زمان اجرا توسط مرورگر دریافت شود (برای نمایش داده های زنده تازه یا تا دقیقه) عالی است. به

داشبورد داده

داده های نشان داده شده در سمت چپ سایت در زمان ساخت درخواست شده و با صفحه Astro در صفحه پخته می شوند. داده های سمت راست صفحه در زمان اجرا با استفاده از درخواست سمت مشتری درخواست می شود. من از نقاط پایانی کمی متفاوت که توسط GitHub REST API نمایان شده است برای پرس و جو از حساب های کاربری مختلف GitHub که لیست های مختلف را ایجاد می کنند ، استفاده کرده ام.

هر آنچه در این سایت می بینید توسط API کاملتر من ارائه شده است. من بهش زنگ زدم: API پائولی و از آن برای تعدادی از وب سایت هایم استفاده می کنم.

API پائولی

API Paulie مانند API این آموزش با Gatsby ساخته شده است ، اما چون Gatsby می تواند هم به عنوان یک سایت و هم به عنوان یک API عمل کند ، من از آن برای مستند کردن نحوه عملکرد همه عملکردهایم استفاده کردم و هر نقطه پایانی دارای صفحه مخصوص خود است که می تواند به عنوان یک تعاملی استفاده شود. زمین بازی… با خیال راحت به اطراف خود نگاه کنید.

بنابراین ، آن را در اختیار دارید ، یک API توابع Gatsby که می تواند توسط هر کد سمت مشتری یا سرور ، از هر وب سایتی که با هر فناوری ساخته شده است استفاده شود. 🤯

این کار را انجام دهید و من بسیار علاقه مند هستم تا ببینم شما چه می سازید. با خیال راحت نظرات زیر را به اشتراک بگذارید یا بیایید مرا در توییتر پیدا کنید: PaulieScanlonبه