API

දළ විශ්ලේෂණය

මෙම මාර්ගෝපදේශය API කාර්යය පිළිබඳවය. අපගේ සම්පූර්ණ API ලේඛන මෙතැනින් සොයාගත හැක මෙතැන.

API ක්වෙස්ට් බාහිර වේදිකාවල ක්වෙස්ට් ස්වයංක්‍රීය කිරීමට භාවිතා කරයි. පරිශීලකයා ලියාපදිංචි වී ඇත්ද හෝ මිලදී ගැනීමක් සිදු කර ඇත්ද, Github හි ගැටලුවක් සඳහා PR එකක් විවෘත කර ඇත්ද, නැතහොත් Reddit සහාය එක් කිරීමට ඔබට එය භාවිතා කළ හැක. හැකියාවන් අසීමිතය. ආරම්භ කිරීමට සහ අප ලබා දෙන ක්‍රියාකාරීත්වය උත්සාහ කිරීමට, වෙනත් Zealy ප්‍රජාවන් සමඟ හවුල්කාරිත්වයන් සිදු කිරීමට ඔබට භාවිතා කළ හැකි මූලික endpoint එකක් අප ලබා දෙයි. එය සැකසීම ගැන තව දැනගන්න.

මූලික කරුණු

"API" කාර්යයක් සෑදීම

1. ක්ලික් කරන්න කාර්යය එකතු කරන්න.
2. තෝරන්න Api.
3. අමතන අන්ත ලක්ෂ්‍යය සහ අවශ්‍ය නම් API යතුරක් නිර්වචනය කරන්න.
4. පරිශීලකයින් හඳුනාගන්නා ආකාරය තෝරන්න. ඔබට තෝරාගත හැක්කේ විද්‍යුත් තැපෑල, Twitter, Discord, පසුම්බි ලිපිනය, හෝ Zealy Connect.

• තෝරා ගන්නේ නම් පසුම්බි සම්බන්ධතාවය, භාවිතා කරන ජාලය ද තෝරා ගත හැක.

• තෝරා ගන්නේ නම් Zealy Connect, මෙම පියවර අනුගමනය කරන්න:

  1. Redirect URL නිර්වචනය කරන්න: මෙම URL සත්‍යාපනය සඳහා භාවිතා වේ. ඔබේ පද්ධතියේ සත්‍යාපනය සඳහා අපි පරිශීලකයින් මෙම URL වෙත යොමු කරමු.

  

  2. ප්‍රජා රහසක් ජනනය කරන්න: ප්‍රජා රහසක් ජනනය කිරීම අවශ්‍ය වේ Zealy Connect ක්‍රියා කිරීමට. ඔබට රහස මෙතැනින් සෑදිය හැක Zealy Connect සැකසුම් යටතේ Integrations කොටස ඔබේ ප්‍රජා සැකසුම් තුළ.

  

APIs ක්‍රියා කරන ආකාරය පිළිබඳ ගැඹුරු තොරතුරු සඳහා කරුණාකර බලන්න API ලේඛන සහ Zealy Connect කළමනාකරණය පිළිබඳ මාර්ගෝපදේශ සඳහා කරුණාකර බලන්න Zealy Connect ලේඛන.

Domino සමඟ ඒකාබද්ධ කිරීම

Domino යනු Web3 Zapier වේ. එය Zealy හි හැකියාවන් දීර්ඝ කිරීමට සහ ස්වදේශීයව ආධාර නොකරන කාර්යයන් ස්වයංක්‍රීයව සමාලෝචනය කිරීමට ඔබට ඉඩ සලසයි, උදාහරණයක් ලෙස:

• පරිශීලකයෙකුගේ Twitter නාමය හෝ ජීව දත්තවල නිශ්චිත වචනයක් අඩංගු දැයි පරීක්ෂා කිරීම
• පරිශීලකයෙකුගේ NFT සහ ටෝකන් ශේෂය පරීක්ෂා කිරීම
• පරිශීලකයෙකු Discord හි නිශ්චිත පිරිසක් ආරාධනා කර ඇත්දැයි සත්‍යාපනය කිරීම
• සහ තවත් බොහෝ දේ

ඔවුන්ගේ ලේඛන ඒකාබද්ධ කිරීම සඳහා බලන්න.

එන්ඩ්පොයින්ට් පරීක්ෂාව

එන්ඩ්පොයින්ට් වින්‍යාස කිරීමේදී එය අපේක්ෂිත පරිදි ක්‍රියා කරන බව තහවුරු කිරීමට අපි පහත පරීක්ෂණ ස්වයංක්‍රීයව ධාවනය කරමු:

1. ඇමතුම තත්පර 10කට වඩා වැඩි නොවන බව පරීක්ෂා කිරීම
2. පරිශීලකයාට පෙන්වීමට හැකි වන පරිදි දෝෂ පණිවිඩය නිවැරදි ආකෘතියෙන් ඇති බව තහවුරු කිරීම
3. අනපේක්ෂිත තත්ත්ව කේත කිසිවක් නොවන බවට වග බලා ගැනීම. එන්ඩ්පොයින්ට් එක 200 හෝ 400 පමණක් ලබා දිය යුතුය.

අභිරුචි එන්ඩ්පොයින්ට් එකක් සෑදීම

ඉල්ලීම

ඔබට API කාර්යයන් අභිරුචි POST එන්ඩ්පොයින්ට් එකක් සමඟ භාවිත කළ හැක, එය පහත ශරීරය පිළිගනී:

{
  /**
   * The user id on Zealy
   */
  userId: string;
  /**
   * Your community id on Zealy, if you use the endpoint
   * on multiple communities this might be useful
   */
  communityId: string;
  /**
   * Your community's subdomain on Zealy, if you use the endpoint
   * on multiple communities this might be useful
   */
  subdomain: string;
  /**
   * The id of the quest
   */
  questId: string;
  /**
   * This will be generated on every claim as a way to look up an error.
   * It will also be displayed for the user when a claim fails.
   */
  requestId: string;
  /**
   * Accounts will be sent if at least one identification method has been configured
   */
  accounts?: {
    /**
     * The user's email address
     */
    email?: string;
    /**
     * The user's Ethereum wallet address that he has authenticated with
     */
    wallet?: string;
    /**
     * The user's Discord id and handle
     */
    discord?: {
      id: string;
      handle: string;
    };
    /**
     * The user's Twitter id and username
     */
    twitter?: {
      id: string;
      username: string;
    };
    /**
     * Your platform user ID stored as part of the Zealy Connect integration
    */
    zealy-connect: string
  };
}

කාර්යය සෑදීමේදී සකසන API යතුරකින් ඔබට එය ආරක්ෂා කළ හැක. API යතුර මෙසේ ශීර්ෂවල යවනු ලැබේ:

{
  "X-Api-Key": apiKey,
}

ප්‍රතිචාරය

පරිශීලකයා විසින් ක්‍රියාව සාර්ථකව සිදු කර ඇත්නම් ඔබ 200 තත්ත්වය. පසුව පරිශීලකයා කාර්යය සාර්ථකව ඉල්ලා සිටිනු ඇත.

{
  "message": "User completed the action"
}

එසේ නොමැති නම්, 400 තත්ත්වය ප්‍රතිචාරයේ ආපසු ලබා දිය යුතු අතර, පණිවිඩයක් ද ඇතුළත් කළ යුතුය. පණිවිඩය ජනනය කරන ලද requestId ඔබට සහ පරිශීලකයාට ගැටළු නිරාකරණය කිරීමට උපකාර කිරීම සඳහා. එය හැකි තරම් විස්තරාත්මක වන බවට වග බලා ගන්න.

{
  "message": "We could not find a user with email kenny@zealy.io"
}

කේත උදාහරණය

// server.js
//
// Use this sample code to handle quest verification in your endpoint.
//
// 1) Paste this code into a new file (server.js)
//
// 2) Install dependencies
//   npm install express
//
// 3) Run the server on http://localhost:3000
//   node server.js
 
const express = require('express');
const app = express();
 
const apiKey = '5888a6800dbac634e52d8504f097e064'; // Replace with your API key configured in Zealy task
 
app.post('/claim', express.raw({ type: 'application/json' }), (req, res) => {
  const payload = req.body;
  const headers = req.headers
 
  if (apiKey !== headers['x-api-key']) {
    throw new Error('Invalid API Key')
  }
 
 
  const success = true; // Replace with custom logic
 
  if (!success) {
    return res.status(400).send({
      message: 'Validation failed' // Replace with custom error message - will be displayed to the user
    })
  }
 
  return res.status(200).send({
    message: "Quest completed"
  })
});
 
app.listen(3000, () => console.log('Running on port 3000'));

ngrok සමඟ දේශීය පරීක්ෂාව

ඔබේ අභිරුචි අන්ත ලක්ෂ්‍යය දේශීයව සංවර්ධනය කර පරීක්ෂා කරන විට, Zealy හට ඔබට API ඉල්ලීම් යැවීමට හැකි වන පරිදි ඔබේ දේශීය සේවාදායකය අන්තර්ජාලයට නිරාවරණය කිරීමට ඔබට ක්‍රමයක් අවශ්‍ය වේ. ngrok යනු localhost වෙත ආරක්ෂිත උමං සාදන මෙවලමක් වන අතර මෙම අරමුණ සඳහා හොඳම වේ. ngrok සැකසීමට සහ ඔබේ අන්ත ලක්ෂ්‍යය පරීක්ෂා කිරීමට මෙම පියවර අනුගමනය කරන්න:

පියවර 1: ngrok ස්ථාපනය කරන්න ngrok හි වෙබ් අඩවියෙන් ngrok බාගන්න. ඔබේ මෙහෙයුම් පද්ධතිය සඳහා ස්ථාපන උපදෙස් අනුගමනය කරන්න.

පියවර 2: ngrok සකසන්න නොමිලේ ngrok ගිණුමක් සඳහා ලියාපදිංචි වී ngrok උපකරණ පුවරුවෙන් ඔබේ authtoken ලබා ගන්න. ඔබේ ටර්මිනලයේ ngrok authtoken YOUR_AUTH_TOKEN ධාවනය කිරීමෙන් ඔබේ ngrok ගිණුම සම්බන්ධ කරන්න, YOUR_AUTH_TOKEN වෙනුවට ඔබේ ngrok උපකරණ පුවරුවේ ඇති ටෝකනය යොදන්න.

පියවර 3: ඔබේ දේශීය සේවාදායකය ආරම්භ කරන්න endpoint එක සත්කාරකත්වය දරන ඔබේ දේශීය සේවාදායකය ධාවනය වෙමින් පවතින බවට වග බලා ගන්න. උදාහරණයක් ලෙස, ඔබේ සේවාදායකය Node.js යෙදුමක් නම්, ඔබ node server.js ධාවනය කළ හැක.

පියවර 4: ngrok සමඟ ඔබේ දේශීය සේවාදායකය නිරාවරණය කරන්න නව ටර්මිනල් කවුළුවක් විවෘත කර ඔබේ දේශීය සේවාදායකයේ පෝටයට (උදා., 3000) ngrok උමං මාර්ගයක් ආරම්භ කරන්න ngrok http http://127.0.0.1:3000. ngrok ටර්මිනලයේ යොමු කිරීමේ URL එකක් පෙන්වයි (උදා., https://abc123.ngrok.io). මෙය Zealy ඔබේ දේශීය සේවාදායකයට ළඟා වීමට භාවිතා කරන පොදු URL එකයි.

පියවර 5: Zealy හි ඔබේ API කාර්යය වින්‍යාස කරන්න Zealy හි ඔබේ API කාර්යය සැකසීමේදී endpoint URL ලෙස ngrok යොමු කිරීමේ URL එක භාවිතා කරන්න. අවශ්‍ය මාර්ගය එකතු කිරීමට වග බලා ගන්න, උදාහරණයක් ලෙස, https://abc123.ngrok.io/claim.

සටහන: මතක තබා ගන්න, ngrok URL යනු තාවකාලික වන අතර ඔබ ngrok නැවත ආරම්භ කරන සෑම විටම වෙනස් වේ, ඔබට අභිරුචි උප වසම් සඳහා සහාය දක්වන ගෙවන දායකත්වයක් නොමැති නම්. ඔබ ngrok නැවත ආරම්භ කරන සෑම විටම Zealy හි endpoint එක යාවත්කාලීන කිරීමට වග බලා ගන්න.

මෙම පියවර අනුගමනය කිරීමෙන්, ඔබට ඔබේ අභිරුචි endpoint එක නිෂ්පාදන සේවාදායකයකට යෙදවීමට පෙර පහසුවෙන් පරීක්ෂා කර දෝෂ නිරාකරණය කළ හැකිය.

Zealy Connect ඒකාබද්ධ කිරීම

Zealy Connect භාවිතා කරන විට, අපි පරිශීලකයා කාර්ය සැකසීමේදී නිශ්චිත කළ URL වෙත හරවා යවන්නෙමු. අපි පහත query params ඇතුළත් කරන්නෙමු:

• zealyUserId: Zealy පද්ධතියේ පරිශීලකයා සඳහා වන අද්විතීය හඳුනාගැනීමක් වන අතර එය ඔබේ වේදිකාව සමඟ සම්බන්ධ කිරීමට භාවිතා වේ.
• callback: සත්යාපනය අවසන් වූ පසු පරිශීලකයා නැවත හරවා යැවීමට ඇති URL, එවිට ඔවුන්ට කාර්යය හිමිකම් කියාගත හැකිය.
• signature: ඉල්ලීමේ සත්යතාව සත්යාපනය කිරීමට භාවිතා කරන SHA-256 hash එකක් වන අතර එය Zealy වෙතින් පැමිණි බව සහතික කරයි.

ආරම්භක ස්ථානයක් ලෙස භාවිතා කළ හැකි සම්පූර්ණ උදාහරණ endpoint එකක් මෙන්න:

 
const YOUR_COMMUNITY_SECRET = "fdb68b155a1ccf2e636c7cd7e0816530"; // Replace with your secret generated in Settings > Integrations > Zealy Connect
 
app.get("/connect", (req, res) => {
  // Extract the query parameters
  const { zealyUserId, signature, callbackUrl } = req.query;
 
  /**
   * Verifying signature to ensure the request is coming from Zealy
   */
  const fullUrl = new URL(
    `${req.protocol}://${req.get("host")}${req.originalUrl}`
  );
  fullUrl.searchParams.delete("signature");
 
  const hmac = crypto.createHmac("sha256", YOUR_COMMUNITY_SECRET);
  hmac.update(fullUrl.toString());
  const generatedSignature = hmac.digest("hex");
 
  if (generatedSignature !== signature){
    return res.status(400).send("Invalid signature");
  }
 
  /**
   * Redirect to login if the user is not authenticated
   */
  if (!req.session.user) {
    res.redirect(`/login?redirect=${encodeURIComponent(req.originalUrl)}`); // Redirect back after the user logs in
  }
 
  /**
   * Save the Zealy User ID (optional)
  */
  // await updateUser(req.session.user.id, { zealyId: zealyUserId });
 
 
  /**
   * Redirect Back to Zealy
   */
  const userId = req.session.user.id; // Replace with your platform user ID
 
  const callbackWithParams = new URL(callbackUrl as string);
  callbackWithParams.searchParams.append("identifier", userId);
 
  const hmac = crypto.createHmac("sha256", YOUR_COMMUNITY_SECRET);
  hmac.update(callbackWithParams.toString());
  const callbackSignature = hmac.digest("hex");
 
  callbackWithParams.searchParams.append("signature", callbackSignature);
 
  res.redirect(callbackWithParams.toString());
});

1. අත්සන සත්‍යාපනය කරන්න

ඔබේ යෙදුම මුලින්ම කළ යුතු දෙය නම් ඔබේ ප්‍රජා රහස භාවිතයෙන් අත්සන සත්‍යාපනය කිරීමයි. මෙම සත්‍යාපනය මගින් එම ඇමතුම සැබවින්ම අපගෙන් පැමිණි එකක් බවත් එය වෙනස් කර නොමැති බවත් තහවුරු කරයි.

අත්සන ජනනය කිරීමට අපි SHA256 හැෂ් ඇල්ගොරිතම භාවිතා කරමු. එය සත්‍යාපනය කිරීමට ඔබට පහත ක්‍රමය භාවිතා කළ හැක:

const fullUrl = new URL(
  `${req.protocol}://${req.get("host")}${req.originalUrl}`
);
fullUrl.searchParams.delete("signature");
 
const hmac = crypto.createHmac("sha256", YOUR_COMMUNITY_SECRET);
hmac.update(fullUrl.toString());
const generatedSignature = hmac.digest("hex");
 
const isSignatureValid = generatedSignature === req.query.signature;

2. Zealy පරිශීලක ID භාවිතා කරන්න

ඊළඟ පියවර ඔබට කිරීමට අවශ්‍ය දෙය මත රඳා පවතී, නමුත් සාමාන්‍යයෙන් ගැනුම්කරුවන් ඔබේ වේදිකාවේ වත්මන් පරිශීලකයා ලොග් කර ඔබේ වේදිකාවේ පරිශීලක ID Zealy පරිශීලක ID සමඟ සම්බන්ධ කරයි. පහත උදාහරණයකි:

  /**
   * Redirect to login if the user is not authenticated
   */
  if (!req.session.user) {
    res.redirect(`/login?redirect=${encodeURIComponent(req.originalUrl)}`); // Redirect back after the user logs in
  }
 
  /**
   * Save the Zealy User ID (optional)
  */
  // await updateUser(req.session.user.id, { zealyId: zealyUserId });
 

3. නැවත Zealy වෙත යොමු කරන්න

අවසාන පියවර වන්නේ අප ලබා දෙන callback query පරාමිතිය භාවිතා කරමින් පරිශීලකයාට කාර්යය හිමිකම් කියා සිටීමට ඉඩ දීම සඳහා ඔබේ වේදිකාවේ පරිශීලක ID සමඟ පරිශීලකයා නැවත Zealy වෙත යොමු කිරීමයි. ඇමතුම ඔබගෙන් පැමිණෙන බවත් වෙනස් නොකළ බවත් සත්‍යාපනය කිරීමට අපට හැකි වන පරිදි ඔබ අත්සනක් ද ජනනය කළ යුතුය. පහත උදාහරණය බලන්න:

const callbackWithParams = new URL(callbackUrl as string);
callbackWithParams.searchParams.append("identifier", connectedUserId); // Set it to your platform user ID
 
const hmac = crypto.createHmac("sha256", YOUR_COMMUNITY_SECRET);
hmac.update(callbackWithParams.toString());
const callbackSignature = hmac.digest("hex");
 
callbackWithParams.searchParams.append("signature", callbackSignature);
 
res.redirect(callbackWithParams.toString());

4. Zealy

අපි callback ලැබුණු පසු අත්සන සත්‍යාපනය කර API කාර්ය පණිවිඩයේ කොටසක් ලෙස යැවීමට හැකි වන පරිදි ඔබේ වේදිකාවේ පරිශීලක ID ගබඩා කරමු.

දැන් පරිශීලකයාට මෙම කාර්යය සහ එම යොමු URL එකම භාවිතා කරන Zealy Connect භාවිතා කරන වෙනත් ඕනෑම කාර්යයක් හිමිකම් කියා සිටීමට හැකි වනු ඇත. සෑම කාර්යයකටම පරිශීලකයාට සම්බන්ධ වීමට අවශ්‍ය නොවන පරිදි අපි මෙය මතක තබා ගනිමු.

ඔබට පරිශීලකයෙකුගේ Zealy Connect සම්බන්ධතාවය මකා දැමීමට අවශ්‍ය නම්, ඔබට භාවිතා කළ හැක්කේ සාමාජික API මාර්ගය සඳහා Zealy Connect මකන්න. මෙම මාර්ගය මගින් නිශ්චිත සාමාජිකයෙකු සඳහා Zealy Connect සම්බන්ධතාවය ඉවත් කිරීමට ඔබට ඉඩ සලසයි. මෙම මාර්ගය ඇමතීමෙන් පසු, Zealy Connect විශේෂාංග නැවත භාවිතා කිරීමට පරිශීලකයාට ඔහුගේ ගිණුම නැවත සම්බන්ධ කිරීමට සිදු වේ.

නිතර අසන ප්‍රශ්න