การเริ่มต้นของ Terra
การเริ่มต้นของ Terra
ในคู่มือเริ่มต้นฉบับย่อนี้ เราจะเริ่มต้นด้วยโครงการ Terra starter แบบง่าย ๆ จากนั้นจึงเสร็จสิ้นด้วยการจัดทำดัชนีข้อมูลจริงบางส่วน นี้จะเป็นการสร้างพื้นฐานให้กับคุณเมื่อตอนที่คุณทำโปรเจกต์ SubQuery ของคุณเอง
หากคุณกำลังมองหาคำแนะนำสำหรับ Substrate/Polkadot คุณสามารถอ่านSubstrate/Polkadot คู่มือการเริ่มต้นฉบับย่อโดยเฉพาะ.
หลังจบคู่มือนี้ คุณจะมีโปรเจ็กต์ SubQuery ที่ทำงานบนโหนด SubQuery และมี GraphQL endpoint ที่คุณสามารถสืบค้นข้อมูลได้
หากคุณยังไม่คุ้นเคย เราขอแนะนำให้คุณทำความคุ้นเคยกับ คำศัพท์ ที่ใช้ใน SubQuery
เป้าหมายของคู่มือเริ่มต้นฉบับย่อนี้คือการปรับโปรเจกต์เริ่มต้นมาตรฐานเพื่อเริ่มสร้างดัชนีการถ่ายโอนทั้งหมดจาก Terra โดยใช้เวลาเพียง 10-15 นาที
การเตรียมความพร้อม
สภาพแวดล้อมสำหรับการพัฒนาภายในตัวเครื่อง
การติดตั้ง SubQuery CLI
ติดตั้ง SubQuery CLI แบบ Global บนเทอมินัลของคุณโดยใช้ NPM
# NPM
npm install -g @subql/cli
โปรดทราบว่าเรา ไม่ สนับสนุนให้ใช้ yarn global
สำหรับการติดตั้ง @subql/cli
เนื่องจากการจัดการ dependency ที่ไม่ได้อาจนำไปสู่ข้อผิดพลาดได้
คุณสามารถเรียกใช้ความช่วยเหลือเพื่อดูคำสั่งและการใช้งานที่ CLI ที่ให้มา
subql help
เริ่มต้น SubQuery Starter Project
ภายใน directory ที่คุณต้องการที่จะสร้าง Subquery Project สามารถรันคำสั่งต่อไปนี้เพื่อเป็นการเริ่มต้น
subql init
คุณจะถูกถามคำถามบางอย่างเมื่อโครงการ SubQuery เริ่มต้น:
- Project Name: A name for your SubQuery project
- ตระกูลเครือข่าย: ตระกูลเครือข่ายบล็อกเชนเลเยอร์ 1 ที่โครงการ SubQuery นี้จะถูกพัฒนาเพื่อสร้างดัชนี ใช้ปุ่มลูกศรบนแป้นพิมพ์เพื่อเลือกจากตัวเลือก สำหรับคำแนะนำนี้ เราจะใช้ "Terra"
- เครือข่าย: เครือข่ายเฉพาะที่โครงการ SubQuery นี้จะถูกพัฒนาเพื่อสร้างดัชนี ใช้ปุ่มลูกศรบนแป้นพิมพ์เพื่อเลือกจากตัวเลือก สำหรับคำแนะนำนี้ เราจะใช้ "Terra"
- แม่แบบ: เลือกเทมเพลตโครงการ SubQuery ที่จะให้จุดเริ่มต้นเพื่อเริ่มการพัฒนา เราขอแนะนำให้เลือก"Starter project"
- Git repository (ทางเลือก): ระบุ Git URL ไปยัง repo ที่โปรเจกต์ SubQuery ที่จะถูกทำการโฮสต์ (เมื่อโฮสต์ใน Subquery Explorer)
- RPC endpoint (จำเป็น): ระบุ HTTPS URL ไปยัง RPC endpoint ที่ทำงานอยู่ที่จะใช้งานเป็นค่าเริ่มต้นของโปรเจค RPC node นี้ต้องเป็น archive node (มีสถานะ full chain state) สำหรับคู่มือนี้เราจะใช้ค่าเริ่มต้นคือ "https://terra-columbus-5.beta.api.onfinality.io"
- Authors (Required): กรอกชื่อเจ้าของโปรเจกต์ที่นี่ (เช่น ชื่อของคุณ)
- Description (ไม่บังคับ): คุณสามารถใส่ข้อความสั้น ๆ เกี่ยวกับโปรเจกต์ของคุณโดยอธิบายว่ามีข้อมูลใดบ้างและผู้ใช้สามารถทำอะไรกับมันได้
- Version (จำเป็น): ระบุหมายเลขเวอร์ชันที่กำหนดเองหรือใช้ค่าเริ่มต้น(
1.0.0
) - License (จำเป็น): ระบุใบอนุญาตซอฟต์แวร์สำหรับโปรเจกต์นี้หรือใช้ค่าเริ่มต้น (
Apache-2.0
)
หลังจากกระบวนการเริ่มต้นเสร็จสมบูรณ์ คุณควรเห็นโฟลเดอร์ที่มีชื่อโปรเจกต์ของคุณถูกสร้างขึ้นภายในไดเร็กทอรี เนื้อหาของไดเร็กทอรีนี้ควรเหมือนกับที่ระบุไว้ใน โครงสร้างไดเร็กทอรี
สุดท้ายแล้วภายใต้โปรเจกต์ไดเร็กทอรี ให้รันคำสั่งต่อไปนี้เพื่อติดตั้งการพึ่งพาของโปรเจกต์ใหม่
::: code-tabs @tab:active yarn shell cd PROJECT_NAME yarn install
ทำการเปลี่ยนแปลงโปรเจกต์ของคุณ
ในแพ็คเกจเริ่มต้นที่คุณเพิ่งเริ่มต้น เราได้จัดเตรียมการกำหนดค่ามาตรฐานสำหรับโปรเจกต์ใหม่ของคุณ คุณจะต้องทำงานกับไฟล์ต่อไปนี้เป็นหลัก:
- The GraphQL Schema ใน
schema.graphql
- The Project Manifest ใน
project.yaml
- Mapping functions ในไดเรกทอรี
src/mappings/
เป้าหมายของบทเริ่มต้นอย่างง่ายของนี้คือ สามารถนำข้อมูลของโปรเจกต์เริ่มต้นเพื่อทำการ indexing ไปยังการโอนย้ายที่ Smart Contract
อัปเดตไฟล์ GraphQL Schema ของคุณ
ไฟล์ schema.graphql
นั้นกำหนด GraphQL schemas ที่หลากหลาย เนื่องจากวิธีที่ภาษา GraphQL ใช้ในการดึงข้อมูลทำงานนั้น ไฟล์ Schema เป็นสิ่งสำคัญที่กำหนดรูปร่างข้อข้อมูลจาก SubQuery มันเป็นจุดที่ดีทีสุดที่จะเริ่มต้นเพราะมันอณุญาตให้คุณกำหนด end goal up front ของคุณได้
เราจะอัปเดตไฟล์ schema.graphql
ให้อ่านดังนี้
type Transfer @entity {
id: ID! # id field ต้องไม่เป็นค่าว่างเสมอ และจะต้องมีลักษณะตามด้านล่างนี้
txHash: String!
blockHeight: BigInt # Block height ของการโอน
sender: String! # บัญชีที่เป็นผู้โอน
recipient: String! # บัญชีที่จะรับโอน
amount: String! # จำนวนที่ถูกโอน
}
สำคัญ: เมื่อคุณได้ทำการเปลี่ยนแปลงใดๆกับไฟล์ schema โปรดตรวจสอบให้มั่นใจว่าคุณสามารถนำชนิดของ directory กลับมาใหม่ได้ ทำแบบนี้เลย
คุณจะเจอรูปแบบที่สร้างขึ้นภายใน /src/types/models
directory. สำหรับข้อมูลเพิ่มเติมภายใน schema.graphql
ไฟล์, โปรดตรวจสอบได้ที่ เอกสารของเราภายใต้ Build/GraphQL Schema
การอับเดท Project Manifest File
The Projet Manifest (project.yaml
)ไฟล์สามารถมองว่าเป็นจุดเริ่มต้นโครงการของคุณและกำหนดรายละเอียดส่วนใหญ่ว่า SubQuery จะสร้างดัชนีและแปลงข้อมูลลูกโซ่อย่างไร
เราจะไม่ทำการเปลี่ยนแปลงใดๆในไฟล์ Manifest เนื่องจากไฟล์ได้รับการตั้งค่าอย่างถูกต้องแล้ว แต่เราจำเป็นต้องเปลี่ยนตัว handlers ของเรา จำไว้ว่าเรากำลังวางแผนที่จะจัดทำดัชนีเหตุการณ์การถ่ายโอน Terra ทั้งหมด ด้วยเหตุนี้ เราจึงต้องอัปเดตส่วน datasources
เพื่ออ่านข้อมูลต่อไปนี้
dataSources:
- kind: terra/Runtime
startBlock: 4724001 # Colombus-5 เริ่มต้นที่บล้อกนี้
mapping:
file: ./dist/index.js
handlers:
- handler: handleEvent
kind: terra/EventHandler
# ส่วนนี้จะถูกเรียกในทุกๆ events ที่ตรงกับเกณท์ต่างๆ ในการคัดกรอง Smart contract t
filter:
type: transfer
messageFilter:
type: /terra.wasm.v1beta1.MsgExecuteContract
values:
# เราได้ทำการติดตาม Smart contract ของ bLuna (e.g. เฉพาะ transfer events จาก contract นี้)
contract: terra1j66jatn3k50hjtg2xemnjm8s7y8dws9xqa5y8w
ซึ่งหมายความว่าเราจะเรียกใช้ mapping function handleEvent
ทุกครั้งที่มีเหตุการณ์ transfer
event จาก Smart contract ขอบ bLuna
สำหรับข้อมูลเพิ่มเติมเกี่ยวกับ Project Manifest (project.yaml
) ไฟล์,โปรดตรวจสอบได้ที่เอกสารของเราภายใต้พ Build/Manifest File
เพิ่ม Mapping Function
Mapping functions กำหนดวิธีการแปลง chain data เป็น GraphQL entities ซึ่งถูกปรับให้เหมาะสมที่เราได้กำหนดไว้ก่อนหน้านี้ในไฟล์ schema.graphql
นำทางไปยัง mapping function เริ่มต้นใน src/mappings
directory คุณจะเห็นสามฟังก์ชันที่ส่งออกมาก, handleBlock
, handleEvent
, and handleCall
. คุณสามารถลบทั้ง handleBlock
และ handleCall
functions, เราจัดการกับ handleEvent
function เท่านั้น
handleEvent
function ได้รับ event data เมื่อใดก็ตามที่เหตุการณ์ตรงกับตัวกรองที่เราระบุไว้ก่อนหน้านี้ในของเราproject.yaml
. เราจะอัปเดตเพื่อประมวลผลกระบวนการทั้งหมดของtransfer
events และบันทึกลงใน GraphQL entities ที่เราสร้างไว้ก่อนหน้านี้
คุณสามารถอัปเดตฟังก์ชัน handleEvent
เป็นดังต่อไปนี้ (โปรดสังเกตการนำเข้าเพิ่มเติม):
import { TerraEvent } from "@subql/types-terra";
import { Transfer } from "../types";
import { MsgExecuteContract } from "@terra-money/terra.js";
export async function handleEvent(
event: TerraEvent<MsgExecuteContract>
): Promise<void> {
// Print debugging data from the event
// logger.info(JSON.stringify(event));
// Create the new transfer entity with a unique ID
const transfer = new Transfer(
`${event.tx.tx.txhash}-${event.msg.idx}-${event.idx}`
);
transfer.blockHeight = BigInt(event.block.block.block.header.height);
transfer.txHash = event.tx.tx.txhash;
for (const attr of event.event.attributes) {
switch (attr.key) {
case "sender":
transfer.sender = attr.value;
break;
case "recipient":
transfer.recipient = attr.value;
break;
case "amount":
transfer.amount = attr.value;
break;
default:
}
}
await transfer.save();
}
สิ่งที่กำลังทำคือการได้รับ SubstrateEvent ซึ่งรวมถึงการถ่ายโอนข้อมูลในส่วนของข้อมูล payload ด้วย เราดึงข้อมูลนี้แล้วสร้าง instantiate entity ใหม่ที่Transfer
ซึ่งเรากำหนดไว้ก่อนหน้านี้ในไฟล์ schema.graphql
เราเพิ่มข้อมูลเพิ่มเติมแล้วใช้ function .save()
เพื่อที่จะบันทึก entity ใหม่ (SubQuery จะบันทึกอัตโนมัติใน database).
สำหรับข้อมูลเพิ่มเติมเกี่ยวกับฟังก์ชันการทำแผนที่ โปรดดูเอกสารประกอบของเราใน Build/Mappings
การสร้างโปรเจค
ในการรันโปรเจกต์ SubQuery ใหม่ของคุณ เราต้องสร้างงานของเราก่อน ทำการ Run คำสั่งเริ่มต้นจาก project's root directory
::: code-tabs @tab:active yarn shell yarn build
@tab npm shell npm run-script build
:::
สำคัญ เมื่อไรก็ตามที่มีการเปลี่ยนแปลงใน Mapping Functions คุณจำเป็นต้องสร้างโปรเจคของคุณใหม่
Running and Querying your Project
รันโปรเจคของคุณกับ Docker
เมื่อไรก็ตามที่คุณสร้าง Subquery Project ใหม่ คุณควรจะรันโปเจค local บนคอมพิวเตอร์ของคุณเสมอเพื่อทดสอบมันก่อน. วิธีที่ง่ายที่สุดคือให้ใช้ Docker
การกำหนดค่าทั้งหมดที่ควบคุมวิธีการรันโหนด SubQuery ถูกกำหนดในสิ่งนี้ docker-compose.yml
file. สำหรับโปรเจกต์ใหม่ที่เพิ่งเริ่มต้น คุณไม่จำเป็นต้องเปลี่ยนแปลงอะไรที่นี่ แต่คุณสามารถอ่านเพิ่มเติมเกี่ยวกับไฟล์และการตั้งค่าใน รันในส่วนของโปรเจกต์
ภายใต้ poject directory ให้รันคำสั่งต่อไปนี้
::: code-tabs @tab:active yarn shell yarn start:docker
@tab npm shell npm run-script start:docker
:::
อาจใช้เวลาสักครู่ในการดาวน์โหลดแพ็คเกจที่จำเป็นสำหรับครั้งแรก (@subql/node
, @subql/query
, and Postgres) แต่ในไม่ช้า คุณจะเห็น SubQuery node ที่ทำงานอยู่ อดทนไว้
Query โปรเจกต์ของคุณ
เปิดเบราว์เซอร์ของคุณและไปที่ http://localhost:3000
คุณควรที่จะเห็น GraphQl playground แสดงใน Explorer และ schemas ที่พร้อมจะสามารถ query ได้ ที่ตำแหน่งด้านบนขวาของ playground คุณจะพบปุ่ม Docs ที่จะเปิดการร่างเอกสาร เอกสารนี้สร้างขึ้นโดยอัตโนมัติและช่วยให้คุณค้นหา entities และ methods ที่คุณสามารถค้นหาได้
สำหรับ Subquery โปรเจคเริ่มต้นใหม่ คุณสามารถลองใช้ query ต่อไปนี้เพื่อดูว่ามันจะทำงานอย่างไร หรือ r เรียนรู้เพิ่มเติมเกี่ยวกับ GraphQL Query language.
{
query {
transfers(first: 10, orderBy: ID_DESC) {
nodes {
id
txHash
amount
blockHeight
sender
recipient
}
}
}
}
เผยแพร่โปรเจกต์ SubQuery ของคุณ
SubQuery ให้บริการที่มีการจัดการฟรีเมื่อคุณปรับใช้โปรเจ็กต์ใหม่ได้ คุณสามารถปรับใช้มัน SubQuery Managed Service และ query โดยใช้ Explorer.
อ่านคำแนะนำเพื่อเผยแพร่โครงการใหม่ของคุณไปยัง SubQuery Projects
ขั้นต่อไป
ยินดีด้วย ตอนนี้คุณได้มี Subquery Project ที่กำลังทำงานอยู่บน local ที่ยอมรับการร้องขอจาก GraphQL API สำหรับการส่งข้อมูล จาก bLuna
ตอนนี้คุณได้รับข้อมูลเชิงลึกเกียวกับสร้าง Subquery project ขั้นพื้นฐาน คำถามคือ เราจะไปที่ไหนต่อ ถ้าคุณคิดว่าคุณมั่นใจ คุณสามารถข้ามไปเรียนรู้เกี่ยวกับ three key files ได้เลย The manifest ไฟล์, the GraphQL schema, และ mappings ไฟล์ภายใต้ Build section of these docs.
หรือไปที่ส่วน Academy ซึ่งมีเวิร์กช็อปเชิงลึก บทแนะนำ และตัวอย่างโครงการเพิ่มเติม เราจะดูการปรับเปลี่ยนขั้นสูงเพิ่มเติมที่นั่น และเราจะเจาะลึกลงไปที่การเรียกใช้โครงการ SubQuery โดยการเรียกใช้โครงการที่พร้อมใช้งานและโอเพ่นซอร์ส
สุดท้ายนี้ หากคุณกำลังมองหาวิธีเพิ่มเติมในการรันและเผยแพร่โปรเจกต์ของคุณ Run & Publish section ของเราสามารถให้ข้อมูลโดยละเอียดเกี่ยวกับวิธีการทั้งหมดในการรันโปรเจกต์ SubQuery ของคุณและการรวบรวม GraphQL ขั้นสูง และ การ subscription features อื่นๆ