ការប្រើប្រាស់ TypeScript SDK (@zinn-digital/sdk)

@zinn-digital/sdk គឺជា TypeScript client ផ្លូវការរបស់យើងសម្រាប់ Zinn Digital® API ដែលត្រូវបានបោះពុម្ពផ្សាយនៅលើ npm។ គ្រប់ path, parameter និង response នៅក្នុងនោះ ត្រូវបានបង្កើតចេញពី OpenAPI specification ដូចគ្នាដែល API ត្រូវបានបង្កើតឡើង ហើយកំណែថ្មីមួយនឹងត្រូវបានបោះពុម្ពផ្សាយដោយស្វ័យប្រវត្តិនៅពេលណាដែល specification នោះមានការផ្លាស់ប្តូរ។ ការណែនាំនេះដំឡើងវា ផ្ទៀងផ្ទាត់ភាពត្រឹមត្រូវវា និងធ្វើការហៅលើកដំបូងរបស់អ្នក។

ដំឡើង

npm install @zinn-digital/sdk

វាដំណើរការក្នុងគ្រប់ runtime របស់ JavaScript ទាំងអស់ដែលមាន fetch៖ Node.js កម្មវិធីរុករក និង edge runtimes។ វាមាន runtime dependency តែមួយគត់គឺ openapi-fetch ហើយវាត្រូវបានផ្តល់អាជ្ញាបណ្ណ MIT។

បង្កើតសោ API

បើកទំព័រ សោ API នៃផ្ទាំងគ្រប់គ្រងរបស់អ្នក (app.zinndigital.com/api-keys) ហើយចុច បង្កើតសោ។ ដាក់ឈ្មោះឱ្យសោ ហើយផ្តល់ត្រឹមតែការអនុញ្ញាតដែលកូដរបស់អ្នកត្រូវការប៉ុណ្ណោះ — ឧទាហរណ៍ sites.view ដើម្បីរាយបញ្ជីគេហទំព័រ។ សោនេះត្រូវបានបង្ហាញតែម្តងគត់ សូមរក្សាទុកវាក្នុង environment variable ឬកន្លែងផ្ទុកការសម្ងាត់របស់អ្នក កុំទុកក្នុង source code ឱ្យសោះ។ អ្នកអាចដកហូតសោនេះនៅពេលណាក៏បាននៅលើទំព័រដដែល។

Endpoints កាតាឡុកសាធារណៈ ដូចជាតំបន់បង្ហោះ និងគម្រោងនានា មិនត្រូវការសោទាល់តែសោះ។

ការហៅលើកដំបូងរបស់អ្នក

import { createApiClient } from "@zinn-digital/sdk";

const api = createApiClient({ baseUrl: "https://api.zinndigital.com" });

// Public catalogue endpoints need no key.
const { data: regions } = await api.GET("/v1/catalog/regions");
console.log(regions?.data.map((r) => r.slug));

// Everything else uses a per-organisation API key.
api.use({
  onRequest({ request }) {
    request.headers.set("Authorization", `Bearer ${process.env.ZINN_API_KEY}`);
  },
});

const { data, error } = await api.GET("/v1/sites", { params: { query: { limit: 5 } } });
if (error) throw new Error(error.error.message);
for (const site of data.data) console.log(site.name, site.status);

ដំណើរការវាជាមួយ ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts។ បន្ទាត់ដំបូងបោះពុម្ពតំបន់បង្ហោះ បន្ទាប់មកមួយបន្ទាត់សម្រាប់គេហទំព័រនីមួយៗ។

ប្រភេទសម្រាប់កូដផ្ទាល់ខ្លួនរបស់អ្នក

ប្រភេទគ្រោងការណ៍ត្រូវបាននាំចេញ ដូច្នេះអនុគមន៍ផ្ទាល់ខ្លួនរបស់អ្នកអាចប្រើទម្រង់របស់ API បាន៖

import type { components } from "@zinn-digital/sdk";

type Site = components["schemas"]["Site"];
type DnsRecord = components["schemas"]["DnsRecord"];

ផ្លូវ ប៉ារ៉ាម៉ែត្រ ឬវាលដែលសរសេរខុស គឺជាកំហុសចងក្រង មិនមែនជាសំណើដែលដំណើរការខុសដោយស្ងាត់ៗនោះទេ។

កំហុស

រាល់ការហៅនីមួយៗត្រឡប់មកវិញនូវ { data, error, response }។ ចំពោះការឆ្លើយតបដែលមិនមែនជា 2xx នោះ data គឺ undefined ហើយ error គឺជាស្រោមព័ត៌មានកំហុសរបស់ API៖ error.error.code, error.error.message ដែលមនុស្សអាចអានបាន ហើយចំពោះការបរាជ័យនៃការផ្ទៀងផ្ទាត់ គឺមាន error.error.details ដែលបញ្ជាក់ឈ្មោះវាលនីមួយៗ។ លេខកូដ 403 មានន័យថាកូនសោមិនមានសិទ្ធិអនុញ្ញាតដែលចំណុចចុងក្រោយត្រូវការទេ — សូមបង្កើតកូនសោដែលមានសិទ្ធិអនុញ្ញាតនោះ ជាជាងការប្រើឡើងវិញនូវកូនសោដែលមានសិទ្ធិច្រើនជាងនេះ។

កន្លែងដែលត្រូវបន្តបន្ទាប់

• មគ្គុទ្ទេសក៍នៅលើគេហទំព័ររបស់យើង៖ zinndigital.com/developers/sdk-typescript
• ចំណុចចុងក្រោយនីមួយៗ ប៉ារ៉ាម៉ែត្រ និងសិទ្ធិអនុញ្ញាតរបស់វា៖ zinndigital.com/developers/api
• កញ្ចប់នៅលើ npm៖ npmjs.com/package/@zinn-digital/sdk