เริ่มต้นสร้างส่วนขยาย

หน้านี้จะแนะนำขั้นตอนที่จำเป็นในการสร้าง Firebase Extension อย่างง่าย ซึ่งคุณสามารถติดตั้งในโปรเจ็กต์หรือแชร์กับผู้อื่นได้ ตัวอย่างง่ายๆ ของ Firebase Extension นี้จะตรวจสอบข้อความใน Realtime Database และแปลงเป็นตัวพิมพ์ใหญ่

1. ตั้งค่าสภาพแวดล้อมและเริ่มต้นโปรเจ็กต์

ก่อนที่จะเริ่มสร้างส่วนขยายได้ คุณจะต้องตั้งค่าสภาพแวดล้อมของบิลด์ ด้วยเครื่องมือที่จำเป็น

  1. ติดตั้ง Node.js 16 ขึ้นไป วิธีหนึ่งในการติดตั้ง Node คือการใช้ nvm (หรือ nvm-windows)

  2. ติดตั้งหรืออัปเดตเป็น Firebase CLI เวอร์ชันล่าสุด หากต้องการ ติดตั้งหรืออัปเดตโดยใช้ npm ให้เรียกใช้คำสั่งนี้

    npm install -g firebase-tools

ตอนนี้ให้ใช้ Firebase CLI เพื่อเริ่มต้นโปรเจ็กต์ส่วนขยายใหม่โดยทำดังนี้

  1. สร้างไดเรกทอรีสำหรับส่วนขยายและ cd ลงในไดเรกทอรีนั้น

    mkdir rtdb-uppercase-messages && cd rtdb-uppercase-messages

  2. เรียกใช้คำสั่ง ext:dev:init ของ Firebase CLI ดังนี้

    firebase ext:dev:init

    เมื่อได้รับข้อความแจ้ง ให้เลือก JavaScript เป็นภาษาสำหรับฟังก์ชัน (แต่โปรดทราบว่าคุณยังใช้ TypeScript ได้เมื่อพัฒนาส่วนขยายของคุณเอง) และเมื่อระบบขอให้ติดตั้งการอ้างอิง ให้ตอบว่า "ใช่" (ยอมรับค่าเริ่มต้นสำหรับ ตัวเลือกอื่นๆ) คำสั่งนี้จะตั้งค่าฐานของโค้ดโครงร่างสำหรับส่วนขยายใหม่ ซึ่งคุณสามารถเริ่มพัฒนาส่วนขยายได้

2. ลองใช้ส่วนขยายตัวอย่างโดยใช้โปรแกรมจำลอง

เมื่อ Firebase CLI เริ่มต้นไดเรกทอรีส่วนขยายใหม่ ระบบจะสร้างฟังก์ชันตัวอย่างอย่างง่ายและไดเรกทอรี integration-tests ซึ่งมีไฟล์ที่จำเป็นต่อการเรียกใช้ส่วนขยายโดยใช้ชุดโปรแกรมจำลอง Firebase

ลองเรียกใช้ส่วนขยายตัวอย่างในโปรแกรมจำลอง

  1. เปลี่ยนไปที่ไดเรกทอรี integration-tests

    cd functions/integration-tests

  2. เริ่มโปรแกรมจำลองด้วยโปรเจ็กต์เดโม

    firebase emulators:start --project=demo-test

    โปรแกรมจำลองจะโหลดส่วนขยายลงในโปรเจ็กต์ "ดัมมี่" ที่กำหนดไว้ล่วงหน้า (demo-test) ส่วนขยายนี้ประกอบด้วยฟังก์ชันที่ทริกเกอร์ด้วย HTTP เพียงฟังก์ชันเดียว greetTheWorld ซึ่งจะแสดงข้อความ "hello world" เมื่อมีการเข้าถึง

  3. ขณะที่โปรแกรมจำลองยังทำงานอยู่ ให้ลองใช้greetTheWorld ฟังก์ชันของส่วนขยายโดยไปที่ URL ที่พิมพ์เมื่อคุณเริ่มใช้งาน

    เบราว์เซอร์จะแสดงข้อความ "Hello World from greet-the-world"

  4. ซอร์สโค้ดของฟังก์ชันนี้อยู่ในไดเรกทอรี functions ของส่วนขยาย เปิดแหล่งข้อมูลในเครื่องมือแก้ไขหรือ IDE ที่คุณเลือก

    functions/index.js

    const functions = require("firebase-functions/v1");

exports.greetTheWorld = functions.https.onRequest((req, res) => {
  // Here we reference a user-provided parameter
  // (its value is provided by the user during installation)
  const consumerProvidedGreeting = process.env.GREETING;

  // And here we reference an auto-populated parameter
  // (its value is provided by Firebase after installation)
  const instanceId = process.env.EXT_INSTANCE_ID;

  const greeting = `${consumerProvidedGreeting} World from ${instanceId}`;

  res.send(greeting);
});

  5. ขณะที่โปรแกรมจำลองทำงานอยู่ โปรแกรมจะโหลดโค้ดฟังก์ชันที่คุณเปลี่ยนแปลงใหม่โดยอัตโนมัติ ลองทำการเปลี่ยนแปลงเล็กน้อยกับฟังก์ชัน greetTheWorld ดังนี้

    functions/index.js

    const greeting = `${consumerProvidedGreeting} everyone, from ${instanceId}`;

    บันทึกการเปลี่ยนแปลง โปรแกรมจำลองจะโหลดโค้ดของคุณซ้ำ และตอนนี้เมื่อคุณ ไปที่ URL ของฟังก์ชัน คุณจะเห็นคำทักทายที่อัปเดตแล้ว

3. เพิ่มข้อมูลพื้นฐานลงใน extension.yaml

เมื่อตั้งค่าสภาพแวดล้อมในการพัฒนาซอฟต์แวร์และเรียกใช้โปรแกรมจำลองส่วนขยายแล้ว คุณก็เริ่มเขียนส่วนขยายของตัวเองได้

ขั้นตอนแรกที่เรียบง่ายคือการแก้ไขข้อมูลเมตาของส่วนขยายที่กำหนดไว้ล่วงหน้าเพื่อให้สอดคล้องกับส่วนขยายที่คุณต้องการเขียนแทน greet-the-world ข้อมูลเมตานี้จะจัดเก็บไว้ในไฟล์ extension.yaml

  1. เปิด extension.yaml ในโปรแกรมแก้ไข แล้วแทนที่เนื้อหาทั้งหมดของไฟล์ ด้วยเนื้อหาต่อไปนี้

    name: rtdb-uppercase-messages
version: 0.0.1
specVersion: v1beta  # Firebase Extensions specification version; don't change

# Friendly display name for your extension (~3-5 words)
displayName: Convert messages to upper case

# Brief description of the task your extension performs (~1 sentence)
description: >-
  Converts messages in RTDB to upper case

author:
  authorName: Your Name
  url: https://your-site.example.com

license: Apache-2.0  # Required license

# Public URL for the source code of your extension
sourceUrl: https://github.com/your-name/your-repo

    โปรดสังเกตรูปแบบการตั้งชื่อที่ใช้ในช่อง name: ส่วนขยาย Firebase อย่างเป็นทางการจะตั้งชื่อโดยมีคำนำหน้าที่ระบุผลิตภัณฑ์ Firebase หลักที่ส่วนขยายทำงานอยู่ ตามด้วยคำอธิบายสิ่งที่ส่วนขยายทำ คุณควรใช้รูปแบบเดียวกันในส่วนขยายของคุณเอง

  2. เนื่องจากคุณได้เปลี่ยนชื่อส่วนขยายแล้ว คุณจึงควรอัปเดตการกำหนดค่าโปรแกรมจำลองด้วยชื่อใหม่ด้วย โดยทำดังนี้

    1. ใน functions/integration-tests/firebase.json ให้เปลี่ยน greet-the-world เป็น rtdb-uppercase-messages
    2. เปลี่ยนชื่อ functions/integration-tests/extensions/greet-the-world.env เป็น functions/integration-tests/extensions/rtdb-uppercase-messages.env

ยังมีร่องรอยของส่วนขยาย greet-the-world บางส่วนเหลืออยู่ใน โค้ดส่วนขยายของคุณ แต่ปล่อยไว้ก่อน คุณจะอัปเดตข้อมูลเหล่านั้นได้ในอีกไม่กี่ ส่วน

4. เขียน Cloud Function และประกาศเป็นทรัพยากรส่วนขยาย

ตอนนี้คุณก็เริ่มเขียนโค้ดได้แล้ว ในขั้นตอนนี้ คุณจะเขียน Cloud Function ที่ทํางานหลักของส่วนขยาย ซึ่งก็คือการดูข้อความในฐานข้อมูลเรียลไทม์และแปลงเป็นตัวพิมพ์ใหญ่

  1. เปิดแหล่งที่มาของฟังก์ชันของส่วนขยาย (ในfunctionsไดเรกทอรีของส่วนขยาย) ในเครื่องมือแก้ไขหรือ IDE ที่คุณเลือก แทนที่เนื้อหาด้วยข้อมูลต่อไปนี้

    functions/index.js

    import { database, logger } from "firebase-functions/v1";

const app = initializeApp();

// Listens for new messages added to /messages/{pushId}/original and creates an
// uppercase version of the message to /messages/{pushId}/uppercase
// for all databases in 'us-central1'
export const makeuppercase = database
  .ref("/messages/{pushId}/uppercase")
  .onCreate(async (snapshot, context) => {
    // Grab the current value of what was written to the Realtime Database.
    const original = snapshot.val();

    // Convert it to upper case.
    logger.log("Uppercasing", context.params.pushId, original);
    const uppercase = original.toUpperCase();

    // Setting an "uppercase" sibling in the Realtime Database.
    const upperRef = snapshot.ref.parent.child("upper");
    await upperRef.set(uppercase);
});

    ฟังก์ชันเดิมที่คุณแทนที่เป็นฟังก์ชันที่ทริกเกอร์ด้วย HTTP ซึ่ง จะทํางานเมื่อมีการเข้าถึงปลายทาง HTTP ฟังก์ชันใหม่จะทริกเกอร์โดย เหตุการณ์ฐานข้อมูลเรียลไทม์: ฟังก์ชันจะตรวจสอบรายการใหม่ในเส้นทางที่เฉพาะเจาะจง และเมื่อตรวจพบรายการใหม่ ฟังก์ชันจะเขียนค่าเวอร์ชันตัวพิมพ์ใหญ่กลับ ไปยังฐานข้อมูล

    อนึ่ง ไฟล์ใหม่นี้ใช้ไวยากรณ์โมดูล ECMAScript (import และ export) แทน CommonJS (require) หากต้องการใช้โมดูล ES ใน Node ให้ระบุ "type": "module" ใน functions/package.json

    {
  "name": "rtdb-uppercase-messages",
  "main": "index.js",
  "type": "module",
  …
}

  2. ฟังก์ชันทุกฟังก์ชันในส่วนขยายต้องประกาศในไฟล์ extension.yaml ส่วนขยายตัวอย่างประกาศ greetTheWorld เป็น Cloud Function เดียวของส่วนขยาย ตอนนี้คุณได้แทนที่ด้วย makeuppercase แล้ว คุณจึงต้อง อัปเดตการประกาศด้วย

    เปิด extension.yaml แล้วเพิ่มฟิลด์ resources ดังนี้

    resources:
  - name: makeuppercase
    type: firebaseextensions.v1beta.function
    properties:
      eventTrigger:
        eventType: providers/google.firebase.database/eventTypes/ref.create
        # DATABASE_INSTANCE (project's default instance) is an auto-populated
        # parameter value. You can also specify an instance.
        resource: projects/_/instances/${DATABASE_INSTANCE}/refs/messages/{pushId}/original
      runtime: "nodejs18"

  3. เนื่องจากตอนนี้ส่วนขยายใช้ Realtime Database เป็นทริกเกอร์ คุณจึงต้องอัปเดตการกำหนดค่าโปรแกรมจำลองเพื่อเรียกใช้โปรแกรมจำลอง RTDB ควบคู่กับโปรแกรมจำลอง Cloud Functions โดยทำดังนี้

    1. หากโปรแกรมจำลองยังทำงานอยู่ ให้หยุดการทำงานโดยกด Ctrl-C

    2. จากไดเรกทอรี functions/integration-tests ให้เรียกใช้คำสั่งต่อไปนี้ 

      firebase init emulators

      เมื่อระบบถาม ให้ข้ามการตั้งค่าโปรเจ็กต์เริ่มต้น แล้วเลือกโปรแกรมจำลองฟังก์ชัน และฐานข้อมูล ยอมรับพอร์ตเริ่มต้นและอนุญาตให้เครื่องมือตั้งค่า ดาวน์โหลดไฟล์ที่จำเป็น

    3. รีสตาร์ทโปรแกรมจำลองโดยทำดังนี้

      firebase emulators:start --project=demo-test

  4. ลองใช้ส่วนขยายที่อัปเดตแล้ว

    1. เปิด UI ของโปรแกรมจำลองฐานข้อมูลโดยใช้ลิงก์ที่โปรแกรมจำลองพิมพ์ออกมา เมื่อคุณเริ่มโปรแกรมจำลอง

    2. แก้ไขโหนดรูทของฐานข้อมูล

      • ฟิลด์: messages
      • ประเภท: json
      • ค่า: {"11": {"original": "recipe"}}

      หากตั้งค่าทุกอย่างถูกต้อง เมื่อบันทึกการเปลี่ยนแปลงฐานข้อมูล ฟังก์ชัน makeuppercase ของส่วนขยายควรทริกเกอร์และเพิ่มระเบียนย่อย ไปยังข้อความ 11 โดยมีเนื้อหา "upper": "RECIPE" ดู ที่แท็บบันทึกและฐานข้อมูลของ UI โปรแกรมจำลองเพื่อยืนยัน ผลลัพธ์ที่คาดไว้

    3. ลองเพิ่มบุตรหลานลงในโหนด messages ({"original":"any text"}) เพิ่มเติม เมื่อใดก็ตามที่คุณเพิ่มระเบียนใหม่ ส่วนขยายควรเพิ่มฟิลด์ uppercase ที่มีเนื้อหาตัวพิมพ์ใหญ่ของฟิลด์ original

ตอนนี้คุณมีส่วนขยายที่สมบูรณ์แม้จะเรียบง่าย ซึ่งทำงานในอินสแตนซ์ RTDB ในส่วนต่อไปนี้ คุณจะได้ปรับแต่งส่วนขยายนี้ด้วยฟีเจอร์เพิ่มเติมบางอย่าง จากนั้นคุณจะเตรียมส่วนขยายให้พร้อมสำหรับการเผยแพร่แก่ผู้อื่น และสุดท้ายคือเรียนรู้วิธีเผยแพร่ส่วนขยายในฮับส่วนขยาย

5. ประกาศ API และบทบาท

Firebase ให้สิทธิ์เข้าถึงแบบจำกัดแก่แต่ละอินสแตนซ์ของส่วนขยายที่ติดตั้งในโปรเจ็กต์และข้อมูลของโปรเจ็กต์โดยใช้บัญชีบริการต่ออินสแตนซ์ แต่ละบัญชีมี ชุดสิทธิ์ขั้นต่ำที่จำเป็นต่อการดำเนินการ ด้วยเหตุนี้ คุณจึงต้องประกาศบทบาท IAM ที่ส่วนขยายของคุณต้องการอย่างชัดเจน เมื่อผู้ใช้ติดตั้งส่วนขยายของคุณ Firebase จะสร้างบัญชีบริการที่มีบทบาทเหล่านี้และใช้บัญชีดังกล่าวเพื่อเรียกใช้ส่วนขยาย

คุณไม่จำเป็นต้องประกาศบทบาทเพื่อทริกเกอร์เหตุการณ์ของผลิตภัณฑ์ แต่คุณต้องประกาศบทบาทเพื่อโต้ตอบกับผลิตภัณฑ์ เนื่องจากฟังก์ชันที่คุณ เพิ่มในขั้นตอนสุดท้ายจะเขียนไปยัง Realtime Database คุณจึงต้องเพิ่ม การประกาศต่อไปนี้ลงใน extension.yaml

roles:
  - role: firebasedatabase.admin
    reason: Allows the extension to write to RTDB.

ในทำนองเดียวกัน คุณจะประกาศ Google API ที่ส่วนขยายใช้ในฟิลด์ apis เมื่อผู้ใช้ติดตั้งส่วนขยาย ระบบจะถามว่าผู้ใช้ต้องการ เปิดใช้ API เหล่านี้โดยอัตโนมัติสำหรับโปรเจ็กต์ของตนหรือไม่ โดยปกติแล้ว คุณจะ ต้องดำเนินการนี้กับ Google API ที่ไม่ใช่ Firebase เท่านั้น และไม่จำเป็นต้องทำตามคู่มือนี้

6. กำหนดพารามิเตอร์ที่ผู้ใช้กำหนดค่าได้

ฟังก์ชันที่คุณสร้างใน 2 ขั้นตอนสุดท้ายจะดูตำแหน่ง RTDB ที่เฉพาะเจาะจง สำหรับข้อความขาเข้า บางครั้งการดูตำแหน่งที่เฉพาะเจาะจงก็เป็นสิ่งที่คุณต้องการจริงๆ เช่น เมื่อส่วนขยายทำงานบนโครงสร้างฐานข้อมูลที่คุณใช้เฉพาะสำหรับส่วนขยาย อย่างไรก็ตาม โดยส่วนใหญ่แล้ว คุณอาจต้องการ ให้ผู้ใช้ที่ติดตั้งส่วนขยายในโปรเจ็กต์ของตน กำหนดค่าเหล่านี้ได้ ด้วยวิธีนี้ ผู้ใช้จะใช้ส่วนขยายของคุณเพื่อทำงานกับการตั้งค่าฐานข้อมูลที่มีอยู่ได้

ทำให้เส้นทางที่ส่วนขยายตรวจสอบข้อความใหม่ที่ผู้ใช้กำหนดค่าได้

  1. ในextension.yamlไฟล์ ให้เพิ่มส่วน params ดังนี้

    - param: MESSAGE_PATH
  label: Message path
  description: >-
    What is the path at which the original text of a message can be found?
  type: string
  default: /messages/{pushId}/original
  required: true
  immutable: false

    ซึ่งจะกำหนดพารามิเตอร์สตริงใหม่ที่ระบบจะแจ้งให้ผู้ใช้ตั้งค่าเมื่อ ติดตั้งส่วนขยาย

  2. ในไฟล์ extension.yaml ให้กลับไปที่makeuppercase ประกาศและเปลี่ยนฟิลด์ resource เป็นดังนี้

    resource: projects/_/instances/${DATABASE_INSTANCE}/refs/${param:MESSAGE_PATH}

    โทเค็น ${param:MESSAGE_PATH} คือการอ้างอิงถึงพารามิเตอร์ที่คุณเพิ่ง กำหนด เมื่อส่วนขยายทำงาน ระบบจะแทนที่โทเค็นนี้ด้วยค่าใดก็ตามที่ผู้ใช้กำหนดค่าไว้สำหรับพารามิเตอร์นั้น ซึ่งจะส่งผลให้ฟังก์ชัน makeuppercase รับฟังเส้นทางที่ผู้ใช้ระบุ คุณ ใช้ไวยากรณ์นี้เพื่ออ้างอิงพารามิเตอร์ที่ผู้ใช้กำหนดได้ทุกที่ใน extension.yaml (และใน POSTINSTALL.md ซึ่งจะกล่าวถึงในภายหลัง)

  3. นอกจากนี้ คุณยังเข้าถึงพารามิเตอร์ที่ผู้ใช้กำหนดจากโค้ดฟังก์ชันได้ด้วย

    ในฟังก์ชันที่คุณเขียนในส่วนสุดท้าย คุณได้ฮาร์ดโค้ดเส้นทางเพื่อ ดูการเปลี่ยนแปลง เปลี่ยนคําจํากัดความทริกเกอร์เพื่ออ้างอิง ค่าที่ผู้ใช้กําหนดแทน

    functions/index.js

    export const makeuppercase = database.ref(process.env.MESSAGE_PATH).onCreate

    โปรดทราบว่าใน Firebase Extensions การเปลี่ยนแปลงนี้มีไว้เพื่อวัตถุประสงค์ในการ จัดทำเอกสารเท่านั้น เมื่อมีการติดตั้งใช้งาน Cloud Functions เป็นส่วนหนึ่งของส่วนขยาย ฟังก์ชันจะใช้คำจำกัดความทริกเกอร์จากไฟล์ extension.yaml และไม่สนใจค่าที่ระบุไว้ในคำจำกัดความฟังก์ชัน อย่างไรก็ตาม คุณควร บันทึกในโค้ดว่าค่านี้มาจากไหน

  4. คุณอาจรู้สึกผิดหวังที่ทำการเปลี่ยนแปลงโค้ดซึ่งไม่มีผลต่อรันไทม์ แต่บทเรียนสำคัญที่ควรจดจำไว้คือคุณสามารถเข้าถึงพารามิเตอร์ที่ผู้ใช้กำหนดในโค้ดฟังก์ชันและใช้เป็นค่าปกติในตรรกะของฟังก์ชันได้ เพื่อเป็นการแสดงให้เห็นถึงความสามารถนี้ ให้เพิ่มคำสั่งบันทึกต่อไปนี้ เพื่อแสดงให้เห็นว่าคุณกำลังเข้าถึงค่าที่ผู้ใช้กำหนดจริงๆ

    functions/index.js

    export const makeuppercase = database.ref(process.env.MESSAGE_PATH).onCreate(
  async (snapshot, context) => {
    logger.log("Found new message at ", snapshot.ref);

    // Grab the current value of what was written to the Realtime Database.
    ...

  5. โดยปกติแล้ว ระบบจะแจ้งให้ผู้ใช้ระบุค่าสำหรับพารามิเตอร์เมื่อผู้ใช้ ติดตั้งส่วนขยาย อย่างไรก็ตาม เมื่อใช้โปรแกรมจำลองสำหรับการทดสอบและการพัฒนา คุณจะข้ามกระบวนการติดตั้งได้ ดังนั้นคุณจึงระบุค่าสำหรับพารามิเตอร์ที่ผู้ใช้กำหนดโดยใช้ไฟล์ env แทน

    เปิด functions/integration-tests/extensions/rtdb-uppercase-messages.env และแทนที่คำจำกัดความของ GREETING ด้วยคำจำกัดความต่อไปนี้

    MESSAGE_PATH=/msgs/{pushId}/original

    โปรดสังเกตว่าเส้นทางด้านบนแตกต่างจากเส้นทางเริ่มต้นและเส้นทางที่คุณกำหนดไว้ก่อนหน้านี้ ซึ่งเป็นเพียงการพิสูจน์ให้คุณเห็นเมื่อลองใช้ส่วนขยายที่อัปเดตแล้วว่าคำจำกัดความของคุณมีผล

  6. ตอนนี้ ให้รีสตาร์ทโปรแกรมจำลอง แล้วไปที่ UI ของโปรแกรมจำลองฐานข้อมูลอีกครั้ง

    แก้ไขโหนดรูทของฐานข้อมูลโดยใช้เส้นทางที่คุณกำหนดไว้ข้างต้น

    • ฟิลด์: msgs
    • ประเภท: json
    • ค่า: {"11": {"original": "recipe"}}

    เมื่อบันทึกการเปลี่ยนแปลงฐานข้อมูล ฟังก์ชัน makeuppercase ของส่วนขยายควรทริกเกอร์เหมือนที่เคย แต่ตอนนี้ควรพิมพ์พารามิเตอร์ที่ผู้ใช้กำหนดลงในบันทึกคอนโซลด้วย

7. ระบุฮุกเหตุการณ์สำหรับตรรกะที่ผู้ใช้กำหนด

ในฐานะผู้เขียนส่วนขยาย คุณได้เห็นแล้วว่าผลิตภัณฑ์ Firebase สามารถทริกเกอร์ตรรกะที่ส่วนขยายของคุณระบุไว้ได้อย่างไร นั่นคือการสร้างระเบียนใหม่ใน Realtime Database จะทริกเกอร์ฟังก์ชัน makeuppercase ส่วนขยายของคุณสามารถมีความสัมพันธ์ที่คล้ายกันกับผู้ใช้ที่ติดตั้งส่วนขยายของคุณได้ นั่นคือ ส่วนขยายสามารถเรียกใช้ตรรกะที่ผู้ใช้กำหนดได้

ส่วนขยายสามารถระบุHook แบบซิงโครนัส Hook แบบอะซิงโครนัส หรือทั้ง 2 อย่าง Hook แบบซิงโครนัสช่วยให้ผู้ใช้สามารถทำงานที่บล็อกการทำงานของฟังก์ชันใดฟังก์ชันหนึ่งของส่วนขยายได้ ซึ่งอาจเป็นประโยชน์ เช่น เพื่อให้ผู้ใช้มีวิธีดำเนินการประมวลผลล่วงหน้าแบบกำหนดเองก่อนที่ส่วนขยายจะทำงาน

ในคู่มือนี้ คุณจะเพิ่ม Hook แบบไม่พร้อมกันลงในส่วนขยาย ซึ่งจะช่วยให้ผู้ใช้กำหนดขั้นตอนการประมวลผลของตนเองที่จะเรียกใช้หลังจากที่ส่วนขยายเขียนข้อความตัวพิมพ์ใหญ่ไปยัง Realtime Database Hook แบบไม่พร้อมกันใช้ Eventarc เพื่อทริกเกอร์ฟังก์ชันที่ผู้ใช้กำหนด ส่วนขยายจะประกาศประเภทเหตุการณ์ที่ปล่อยออกมา และ เมื่อผู้ใช้ติดตั้งส่วนขยาย ผู้ใช้จะเลือกประเภทเหตุการณ์ที่ตนเองสนใจ หากเลือกเหตุการณ์อย่างน้อย 1 รายการ Firebase จะจัดสรรแชแนล Eventarc ให้ส่วนขยายเป็นส่วนหนึ่งของกระบวนการติดตั้ง จากนั้นผู้ใช้ จะสามารถติดตั้งใช้งานฟังก์ชันระบบคลาวด์ของตนเองที่รับฟังในช่องดังกล่าวและ ทริกเกอร์เมื่อส่วนขยายเผยแพร่เหตุการณ์ใหม่

ทำตามขั้นตอนต่อไปนี้เพื่อเพิ่ม Hook แบบอะซิงโครนัส

  1. ในไฟล์ extension.yaml ให้เพิ่มส่วนต่อไปนี้ ซึ่งประกาศประเภทเหตุการณ์เดียวที่ส่วนขยายปล่อยออกมา

    events:
  - type: test-publisher.rtdb-uppercase-messages.v1.complete
    description: >-
      Occurs when message uppercasing completes. The event subject will contain
      the RTDB URL of the uppercase message.

    ประเภทเหตุการณ์ต้องไม่ซ้ำกันในทุกที่ เพื่อให้มั่นใจว่าไม่ซ้ำกัน ให้ตั้งชื่อเหตุการณ์โดยใช้รูปแบบต่อไปนี้เสมอ <publisher-id>.<extension-id>.<version>.<description> (คุณยังไม่มีรหัสผู้เผยแพร่โฆษณา จึงใช้ test-publisher ไปก่อน)

  2. ที่ส่วนท้ายของฟังก์ชัน makeuppercase ให้เพิ่มโค้ดที่เผยแพร่เหตุการณ์ ประเภทที่คุณเพิ่งประกาศ

    functions/index.js

    // Import the Eventarc library:
import { initializeApp } from "firebase-admin/app";
import { getEventarc } from "firebase-admin/eventarc";

const app = initializeApp();

// In makeuppercase, after upperRef.set(uppercase), add:

// Set eventChannel to a newly-initialized channel, or `undefined` if events
// aren't enabled.
const eventChannel =
  process.env.EVENTARC_CHANNEL &&
  getEventarc().channel(process.env.EVENTARC_CHANNEL, {
    allowedEventTypes: process.env.EXT_SELECTED_EVENTS,
  });

// If events are enabled, publish a `complete` event to the configured
// channel.
eventChannel &&
  eventChannel.publish({
    type: "test-publisher.rtdb-uppercase-messages.v1.complete",
    subject: upperRef.toString(),
    data: {
      "original": original,
      "uppercase": uppercase,
    },
  });

    โค้ดตัวอย่างนี้ใช้ประโยชน์จากข้อเท็จจริงที่ว่าตัวแปรสภาพแวดล้อม EVENTARC_CHANNEL จะกำหนดก็ต่อเมื่อผู้ใช้เปิดใช้ประเภทเหตุการณ์อย่างน้อย 1 ประเภทเท่านั้น หากไม่ได้กำหนด EVENTARC_CHANNEL โค้ดจะไม่พยายาม เผยแพร่เหตุการณ์ใดๆ

    คุณแนบข้อมูลเพิ่มเติมกับเหตุการณ์ Eventarc ได้ ในตัวอย่างข้างต้น เหตุการณ์มีฟิลด์ subject ที่มีการอ้างอิงถึง ค่าที่สร้างขึ้นใหม่ และเพย์โหลด data ที่มีข้อความเดิมและ ข้อความตัวพิมพ์ใหญ่ ฟังก์ชันที่ผู้ใช้กำหนดซึ่งทริกเกอร์จากเหตุการณ์จะใช้ข้อมูลนี้ได้

  3. โดยปกติแล้ว ระบบจะกำหนดตัวแปรสภาพแวดล้อม EVENTARC_CHANNEL และ EXT_SELECTED_EVENTS ตามตัวเลือกที่ผู้ใช้เลือกในระหว่างการติดตั้ง หากต้องการทดสอบด้วยโปรแกรมจำลอง ให้กำหนดตัวแปรต่อไปนี้ด้วยตนเอง ในไฟล์ rtdb-uppercase-messages.env

    EVENTARC_CHANNEL=locations/us-central1/channels/firebase
EXT_SELECTED_EVENTS=test-publisher.rtdb-uppercase-messages.v1.complete

ตอนนี้คุณได้ทำตามขั้นตอนที่จำเป็นในการเพิ่ม Hook เหตุการณ์แบบไม่พร้อมกัน ลงในส่วนขยายแล้ว

หากต้องการลองใช้ฟีเจอร์ใหม่นี้ที่คุณเพิ่งติดตั้งใช้งาน ให้ทำตามขั้นตอนต่อไปนี้โดยสวมบทบาทเป็นผู้ใช้ที่กำลังติดตั้งส่วนขยาย

  1. จากไดเรกทอรี functions/integration-tests ให้เริ่มต้นโปรเจ็กต์ Firebase ใหม่โดยทำดังนี้

    firebase init functions

    เมื่อได้รับข้อความแจ้ง ให้ปฏิเสธการตั้งค่าโปรเจ็กต์เริ่มต้น เลือก JavaScript เป็นภาษา Cloud Functions และติดตั้งการอ้างอิงที่จำเป็น โปรเจ็กต์นี้แสดงถึงโปรเจ็กต์ของผู้ใช้ซึ่งติดตั้งส่วนขยายของคุณ

  2. แก้ไข integration-tests/functions/index.js แล้ววางโค้ดต่อไปนี้

    import { logger } from "firebase-functions/v1";
import { onCustomEventPublished } from "firebase-functions/v2/eventarc";

import { initializeApp } from "firebase-admin/app";
import { getDatabase } from "firebase-admin/database";

const app = initializeApp();

export const extraemphasis = onCustomEventPublished(
  "test-publisher.rtdb-uppercase-messages.v1.complete",
  async (event) => {
    logger.info("Received makeuppercase completed event", event);

    const refUrl = event.subject;
    const ref = getDatabase().refFromURL(refUrl);
    const upper = (await ref.get()).val();
    return ref.set(`${upper}!!!`);
  }
);

    นี่คือตัวอย่างฟังก์ชันการประมวลผลภายหลังที่ผู้ใช้อาจเขียนขึ้น ในกรณีนี้ ฟังก์ชันจะรอให้ส่วนขยายเผยแพร่completeเหตุการณ์ และเมื่อทริกเกอร์แล้ว จะเพิ่มเครื่องหมายอัศเจรีย์ 3 ตัวลงในข้อความที่เพิ่งเปลี่ยนเป็นตัวพิมพ์ใหญ่

  3. รีสตาร์ทโปรแกรมจำลอง โปรแกรมจำลองจะโหลดฟังก์ชันของส่วนขยาย รวมถึงฟังก์ชันการประมวลผลภายหลังที่ "ผู้ใช้" กำหนด

  4. ไปที่ UI ของโปรแกรมจำลองฐานข้อมูลและแก้ไขโหนดรูทของฐานข้อมูลโดยใช้ เส้นทางที่คุณกำหนดไว้ข้างต้น

    • ฟิลด์:msgs
    • ประเภท: json
    • ค่า: {"11": {"original": "recipe"}}

    เมื่อบันทึกการเปลี่ยนแปลงฐานข้อมูล makeuppercaseฟังก์ชัน ของส่วนขยายและฟังก์ชัน extraemphasis ของผู้ใช้ควรทริกเกอร์ตามลำดับ ส่งผลให้ฟิลด์ upper ได้ค่า RECIPE!!!

8. เพิ่มตัวแฮนเดิลเหตุการณ์ในวงจร

ส่วนขยายที่คุณเขียนไว้จนถึงตอนนี้จะประมวลผลข้อความเมื่อมีการสร้าง แต่จะเกิดอะไรขึ้นหากผู้ใช้มีฐานข้อมูลข้อความอยู่แล้วเมื่อติดตั้งส่วนขยาย Firebase Extensions มีฟีเจอร์ที่เรียกว่าฮุกเหตุการณ์ในวงจร ซึ่งคุณใช้เพื่อทริกเกอร์การดำเนินการได้เมื่อติดตั้ง อัปเดต หรือกำหนดค่าส่วนขยายใหม่ ในส่วนนี้ คุณจะใช้ฮุกเหตุการณ์ในวงจรเพื่อเติมข้อมูลย้อนหลังให้กับฐานข้อมูลข้อความที่มีอยู่ของโปรเจ็กต์ด้วยข้อความตัวพิมพ์ใหญ่เมื่อผู้ใช้ติดตั้งส่วนขยาย

Firebase Extensions ใช้ Cloud Tasks เพื่อเรียกใช้ตัวแฮนเดิลเหตุการณ์ในวงจร คุณ กำหนดเครื่องจัดการเหตุการณ์โดยใช้ Cloud Functions เมื่อใดก็ตามที่อินสแตนซ์ของ ส่วนขยายถึงเหตุการณ์วงจรการใช้งานที่รองรับรายการใดรายการหนึ่ง หากคุณได้กำหนด เครื่องจัดการไว้ ระบบจะเพิ่มเครื่องจัดการนั้นลงในคิว Cloud Tasks จากนั้น Cloud Tasks จะ เรียกใช้แฮนเดิลแบบไม่พร้อมกัน ขณะที่ตัวแฮนเดิลเหตุการณ์ในวงจรทํางาน คอนโซล Firebase จะรายงานให้ผู้ใช้ทราบว่าอินสแตนซ์ของส่วนขยายมีงานการประมวลผลที่กําลังดําเนินการอยู่ ฟังก์ชันตัวแฮนเดิลมีหน้าที่รายงานสถานะที่กำลังดำเนินการ และความสําเร็จของงานกลับไปยังผู้ใช้

หากต้องการเพิ่มตัวแฮนเดิลเหตุการณ์ในวงจรที่เติมข้อความที่มีอยู่ ให้ทำดังนี้

  1. กำหนด Cloud Function ใหม่ที่ทริกเกอร์โดยเหตุการณ์คิวงาน

    functions/index.js

    import { tasks } from "firebase-functions/v1";

import { getDatabase } from "firebase-admin/database";
import { getExtensions } from "firebase-admin/extensions";
import { getFunctions } from "firebase-admin/functions";

export const backfilldata = tasks.taskQueue().onDispatch(async () => {
  const batch = await getDatabase()
    .ref(process.env.MESSAGE_PATH)
    .parent.parent.orderByChild("upper")
    .limitToFirst(20)
    .get();

  const promises = [];
  for (const key in batch.val()) {
    const msg = batch.child(key);
    if (msg.hasChild("original") && !msg.hasChild("upper")) {
      const upper = msg.child("original").val().toUpperCase();
      promises.push(msg.child("upper").ref.set(upper));
    }
  }
  await Promise.all(promises);

  if (promises.length > 0) {
    const queue = getFunctions().taskQueue(
      "backfilldata",
      process.env.EXT_INSTANCE_ID
    );
    return queue.enqueue({});
  } else {
    return getExtensions()
      .runtime()
      .setProcessingState("PROCESSING_COMPLETE", "Backfill complete.");
  }
});

    โปรดทราบว่าฟังก์ชันจะประมวลผลเฉพาะบางระเบียนก่อนที่จะเพิ่มตัวเอง กลับไปที่คิวงาน นี่เป็นกลยุทธ์ที่ใช้กันโดยทั่วไปในการจัดการกับ งานการประมวลผลที่ทำไม่เสร็จภายในกรอบเวลาการหมดเวลาของ Cloud Functions เนื่องจากคุณไม่สามารถคาดการณ์ได้ว่าผู้ใช้อาจมีข้อความในฐานข้อมูลอยู่แล้วกี่ข้อความเมื่อติดตั้งส่วนขยาย กลยุทธ์นี้จึงเหมาะอย่างยิ่ง

  2. ในไฟล์ extension.yaml ให้ประกาศฟังก์ชันการแสดงโฆษณาสำรองเป็นทรัพยากรส่วนขยาย ที่มีพร็อพเพอร์ตี้ taskQueueTrigger

    resources:
  - name: makeuppercase
    ...
  - name: backfilldata
    type: firebaseextensions.v1beta.function
    description: >-
      Backfill existing messages with uppercase versions
    properties:
      runtime: "nodejs18"
      taskQueueTrigger: {}

    จากนั้นประกาศฟังก์ชันเป็นตัวแฮนเดิลสำหรับเหตุการณ์onInstallวงจร 

    lifecycleEvents:
  onInstall:
    function: backfilldata
    processingMessage: Uppercasing existing messages

  3. แม้ว่าการป้อนข้อมูลย้อนหลังสำหรับข้อความที่มีอยู่จะเป็นเรื่องดี แต่ส่วนขยายก็ยังคงทำงานได้โดยไม่มีการป้อนข้อมูลย้อนหลัง ในสถานการณ์เช่นนี้ คุณควรทำให้การเรียกใช้ตัวแฮนเดิลเหตุการณ์ในวงจรเป็นตัวเลือก

    โดยให้เพิ่มพารามิเตอร์ใหม่ลงใน extension.yaml ดังนี้

    - param: DO_BACKFILL
  label: Backfill existing messages
  description: >-
    Generate uppercase versions of existing messages?
  type: select
  required: true
  options:
    - label: Yes
      value: true
    - label: No
      value: false

    จากนั้นที่จุดเริ่มต้นของฟังก์ชันการแสดงโฆษณาสำรอง ให้ตรวจสอบค่าของพารามิเตอร์ DO_BACKFILL และออกก่อนหากไม่ได้ตั้งค่าไว้

    functions/index.js

    if (!process.env.DO_BACKFILL) {
  return getExtensions()
    .runtime()
    .setProcessingState("PROCESSING_COMPLETE", "Backfill skipped.");
}

การเปลี่ยนแปลงข้างต้นจะทำให้ส่วนขยายแปลงข้อความที่มีอยู่เป็นตัวพิมพ์ใหญ่เมื่อติดตั้ง

จนถึงตอนนี้ คุณได้ใช้โปรแกรมจำลองส่วนขยายเพื่อพัฒนาส่วนขยายและ ทดสอบการเปลี่ยนแปลงที่กำลังดำเนินการอยู่ อย่างไรก็ตาม โปรแกรมจำลองส่วนขยายจะข้ามกระบวนการติดตั้ง ดังนั้นหากต้องการทดสอบonInstallตัวแฮนเดิลเหตุการณ์ คุณจะต้องติดตั้ง ส่วนขยายในโปรเจ็กต์จริง แต่ก็ไม่เป็นไร เพราะตอนนี้ส่วนขยายบทแนะนำก็มีโค้ดครบถ้วนแล้วเนื่องจากเราได้เพิ่มฟีเจอร์การแสดงโฆษณาสำรองอัตโนมัตินี้

9. ทําให้ใช้งานได้ในโปรเจ็กต์ Firebase จริง

แม้ว่าโปรแกรมจำลองส่วนขยายจะเป็นเครื่องมือที่ยอดเยี่ยมสำหรับการทำซ้ำส่วนขยายอย่างรวดเร็วในระหว่างการพัฒนา แต่ในบางครั้งคุณก็อาจต้องการลองใช้ในโปรเจ็กต์จริง

โดยให้ตั้งค่าโปรเจ็กต์ใหม่และเปิดใช้บริการบางอย่างก่อน ดังนี้

  1. ในคอนโซล Firebase ให้เพิ่มโปรเจ็กต์ใหม่
  2. อัปเกรดโปรเจ็กต์ เป็นแพ็กเกจ Blaze แบบจ่ายเมื่อใช้ Cloud Functions for Firebase กำหนดให้โปรเจ็กต์ต้องมีบัญชีสำหรับการเรียกเก็บเงิน ดังนั้นคุณจึงต้องมีบัญชีสำหรับการเรียกเก็บเงินเพื่อติดตั้งส่วนขยายด้วย
  3. เปิดใช้ Realtime Database ในโปรเจ็กต์ใหม่
  4. เนื่องจากคุณต้องการทดสอบความสามารถของส่วนขยายในการกรอกข้อมูลย้อนหลังที่มีอยู่เมื่อติดตั้ง ให้คุณนําเข้าข้อมูลตัวอย่างบางส่วนลงในอินสแตนซ์ฐานข้อมูลเรียลไทม์
    1. ดาวน์โหลดข้อมูล RTDB เริ่มต้น
    2. ในหน้า Realtime Database ของคอนโซล Firebase ให้คลิก (เพิ่มเติม) > นำเข้า JSON แล้วเลือกไฟล์ที่คุณเพิ่งดาวน์โหลด

  5. หากต้องการเปิดใช้ฟังก์ชันการแสดงโฆษณาสำรองเพื่อใช้วิธี orderByChild ให้กำหนดค่า ฐานข้อมูลเพื่อจัดทำดัชนีข้อความตามค่าของ upper ดังนี้

    {
  "rules": {
    ".read": false,
    ".write": false,
    "messages": {
      ".indexOn": "upper"
    }
  }
}

ตอนนี้ให้ติดตั้งส่วนขยายจากแหล่งที่มาในเครื่องไปยังโปรเจ็กต์ใหม่

  1. สร้างไดเรกทอรีใหม่สำหรับโปรเจ็กต์ Firebase โดยทำดังนี้

    mkdir ~/extensions-live-test && cd ~/extensions-live-test

  2. เริ่มต้นโปรเจ็กต์ Firebase ในไดเรกทอรีการทำงานโดยทำดังนี้

    firebase init database

    เมื่อได้รับข้อความแจ้ง ให้เลือกโปรเจ็กต์ที่คุณเพิ่งสร้าง

  3. ติดตั้งส่วนขยายลงในโปรเจ็กต์ Firebase ในเครื่องโดยทำดังนี้

    firebase ext:install /path/to/rtdb-uppercase-messages

    ที่นี่คุณจะเห็นประสบการณ์ของผู้ใช้เมื่อติดตั้งส่วนขยายโดยใช้เครื่องมือ Firebase CLI อย่าลืมเลือก "ใช่" เมื่อเครื่องมือ การกำหนดค่าถามว่าคุณต้องการทำการป้อนข้อมูลย้อนหลังในฐานข้อมูลที่มีอยู่หรือไม่

    หลังจากเลือกตัวเลือกการกำหนดค่าแล้ว Firebase CLI จะบันทึกการกำหนดค่าในไดเรกทอรี extensions และบันทึกตำแหน่งแหล่งที่มาของส่วนขยายในไฟล์ firebase.json โดยรวมแล้ว เรคคอร์ดทั้ง 2 รายการนี้เรียกว่าไฟล์ Manifest ของส่วนขยาย ผู้ใช้สามารถใช้ไฟล์ Manifest เพื่อบันทึกการกำหนดค่าส่วนขยายและนำไปใช้กับโปรเจ็กต์ต่างๆ ได้

  4. ทําการกําหนดค่าส่วนขยายกับโปรเจ็กต์ที่ใช้งานจริงโดยทําดังนี้

    firebase deploy --only extensions

หากทุกอย่างเป็นไปด้วยดี Firebase CLI ควรจะอัปโหลดส่วนขยายไปยังโปรเจ็กต์ และติดตั้งส่วนขยาย หลังจากติดตั้งเสร็จแล้ว งานการแสดงโฆษณาสำรองจะทำงาน และในอีกไม่กี่นาที ฐานข้อมูลจะได้รับการอัปเดตด้วยข้อความตัวพิมพ์ใหญ่ เพิ่มโหนดใหม่ลงในฐานข้อมูลข้อความและตรวจสอบว่าส่วนขยายทำงานกับข้อความใหม่ด้วย

10. เขียนเอกสารประกอบ

ก่อนแชร์ส่วนขยายกับผู้ใช้ โปรดตรวจสอบว่าคุณได้จัดทำเอกสารที่เพียงพอ เพื่อให้ผู้ใช้ใช้งานได้สำเร็จ

เมื่อคุณเริ่มต้นโปรเจ็กต์ส่วนขยาย Firebase CLI จะสร้างเอกสารเวอร์ชัน Stub ของเอกสารขั้นต่ำที่จำเป็น อัปเดตไฟล์เหล่านี้เพื่อให้แสดงส่วนขยายที่คุณสร้างได้อย่างถูกต้อง

extension.yaml

คุณได้อัปเดตไฟล์นี้อยู่แล้วขณะพัฒนาส่วนขยายนี้ ดังนั้น คุณจึงไม่จำเป็นต้องอัปเดตเพิ่มเติมในตอนนี้

อย่างไรก็ตาม อย่ามองข้ามความสำคัญของเอกสารที่อยู่ในไฟล์นี้ นอกเหนือจากข้อมูลระบุตัวตนที่สำคัญของส่วนขยาย ได้แก่ ชื่อ คำอธิบาย ผู้เขียน และที่ตั้งของที่เก็บอย่างเป็นทางการแล้ว extension.yaml ไฟล์ยังมีเอกสารประกอบที่ผู้ใช้มองเห็นสำหรับทรัพยากรทุกรายการและพารามิเตอร์ที่ผู้ใช้กำหนดค่าได้ ข้อมูลนี้จะแสดงต่อผู้ใช้ในคอนโซล Firebase, ศูนย์กลางส่วนขยาย และ Firebase CLI

PREINSTALL.md

ในไฟล์นี้ ให้ระบุข้อมูลที่ผู้ใช้จำเป็นต้องทราบก่อนติดตั้งส่วนขยาย ของคุณ อธิบายสั้นๆ ว่าส่วนขยายทำอะไร อธิบายข้อกำหนดเบื้องต้น และให้ข้อมูลแก่ผู้ใช้เกี่ยวกับผลกระทบด้านการเรียกเก็บเงินของการติดตั้ง ส่วนขยาย หากคุณมีเว็บไซต์ที่มีข้อมูลเพิ่มเติม คุณก็สามารถลิงก์เว็บไซต์นั้นได้เช่นกัน

ข้อความในไฟล์นี้จะแสดงต่อผู้ใช้ในฮับส่วนขยายและโดยคำสั่ง firebase ext:info

ตัวอย่างไฟล์ PREINSTALL มีดังนี้

Use this extension to automatically convert strings to upper case when added to
a specified Realtime Database path.

This extension expects a database layout like the following example:

    "messages": {
      MESSAGE_ID: {
        "original": MESSAGE_TEXT
      },
      MESSAGE_ID: {
        "original": MESSAGE_TEXT
      },
    }

When you create new string records, this extension creates a new sibling record
with upper-cased text:

    MESSAGE_ID: {
      "original": MESSAGE_TEXT,
      "upper": UPPERCASE_MESSAGE_TEXT,
    }

#### Additional setup

Before installing this extension, make sure that you've
[set up Realtime Database](https://firebase.google.com/docs/database/quickstart)
in your Firebase project.

#### Billing

To install an extension, your project must be on the
[Blaze (pay as you go) plan](https://firebase.google.com/pricing).

- This extension uses other Firebase and Google Cloud Platform services, which
  have associated charges if you exceed the service's no-cost tier:
  - Realtime Database
  - Cloud Functions (Node.js 10+ runtime)
    [See FAQs](/docs/functions/faq-and-troubleshooting#extensions-pricing)
- If you enable events,
  [Eventarc fees apply](https://cloud.google.com/eventarc/pricing).

POSTINSTALL.md

ไฟล์นี้มีข้อมูลที่เป็นประโยชน์สำหรับผู้ใช้หลังจากที่ติดตั้งส่วนขยายสำเร็จแล้ว เช่น ขั้นตอนการตั้งค่าติดตาม ตัวอย่างของ ส่วนขยายที่ใช้งานจริง และอื่นๆ

เนื้อหาของ POSTINSTALL.md จะแสดงในคอนโซล Firebase หลังจากที่กำหนดค่าและติดตั้ง ส่วนขยายแล้ว คุณอ้างอิงพารามิเตอร์ผู้ใช้ในไฟล์นี้ได้ และระบบจะแทนที่ด้วยค่าที่กำหนด

ต่อไปนี้คือตัวอย่างไฟล์หลังการติดตั้งสำหรับส่วนขยายบทแนะนำ

### See it in action

You can test out this extension right away!

1.  Go to your
    [Realtime Database dashboard](https://console.firebase.google.com/project/${param:PROJECT_ID}/database/${param:PROJECT_ID}/data) in the Firebase console.

1.  Add a message string to a path that matches the pattern `${param:MESSAGE_PATH}`.

1.  In a few seconds, you'll see a sibling node named `upper` that contains the
    message in upper case.

### Using the extension

We recommend adding data by pushing -- for example,
`firebase.database().ref().push()` -- because pushing assigns an automatically
generated ID to the node in the database. During retrieval, these nodes are
guaranteed to be ordered by the time they were added. Learn more about reading
and writing data for your platform (iOS, Android, or Web) in the
[Realtime Database documentation](https://firebase.google.com/docs/database/).

### Monitoring

As a best practice, you can
[monitor the activity](https://firebase.google.com/docs/extensions/manage-installed-extensions#monitor)
of your installed extension, including checks on its health, usage, and logs.

CHANGELOG.md

นอกจากนี้ คุณควรบันทึกการเปลี่ยนแปลงที่ทำระหว่างการเผยแพร่ส่วนขยาย ในไฟล์ CHANGELOG.md ด้วย

เนื่องจากส่วนขยายตัวอย่างไม่เคยเผยแพร่มาก่อน บันทึกการเปลี่ยนแปลงจึงมีรายการเดียวเท่านั้น

## Version 0.0.1

Initial release of the _Convert messages to upper case_ extension.

README.md

ส่วนใหญ่แล้วส่วนขยายจะมีไฟล์ README เพื่อประโยชน์ของผู้ใช้ที่เข้าชมที่เก็บของส่วนขยาย คุณสามารถเขียนไฟล์นี้ด้วยตนเองหรือสร้างไฟล์ README โดยใช้คำสั่ง

สำหรับคู่มือนี้ ให้ข้ามการเขียนไฟล์ README

เอกสารประกอบเพิ่มเติม

เอกสารที่กล่าวถึงข้างต้นเป็นชุดเอกสารขั้นต่ำที่คุณควร จัดเตรียมให้แก่ผู้ใช้ ส่วนขยายหลายรายการต้องมีเอกสารประกอบที่ละเอียดมากขึ้นเพื่อให้ผู้ใช้ ใช้งานได้สำเร็จ ในกรณีนี้ คุณควรเขียนเอกสารเพิ่มเติม และโฮสต์ไว้ในที่ที่คุณสามารถชี้ให้ผู้ใช้ไปได้

สำหรับวัตถุประสงค์ของคู่มือนี้ ให้ข้ามการเขียนเอกสารประกอบที่ครอบคลุมยิ่งขึ้น

11. เผยแพร่ในฮับส่วนขยาย

เมื่อเขียนโค้ดส่วนขยายเสร็จและจัดทำเอกสารแล้ว คุณก็พร้อมแชร์ส่วนขยายกับผู้ใช้ทั่วโลกในฮับส่วนขยาย แต่เนื่องจากนี่เป็นเพียงบทแนะนำ จึงไม่ ต้องทำตามจริงๆ ไปเริ่มเขียนส่วนขยายของคุณเองโดยใช้สิ่งที่ได้เรียนรู้ที่นี่และในเอกสารประกอบอื่นๆ ของผู้เผยแพร่ส่วนขยาย Firebase รวมถึงการตรวจสอบแหล่งที่มาของส่วนขยายอย่างเป็นทางการที่ Firebase เขียนขึ้น

เมื่อพร้อมเผยแพร่ผลงานในฮับส่วนขยายแล้ว คุณจะทำได้ดังนี้

  1. หากคุณเผยแพร่ส่วนขยายเป็นครั้งแรก ให้ลงทะเบียนเป็นผู้เผยแพร่ส่วนขยาย เมื่อลงทะเบียนเป็นผู้เผยแพร่ส่วนขยาย คุณจะสร้างรหัสผู้เผยแพร่ที่ช่วยให้ผู้ใช้ระบุตัวตนของคุณในฐานะผู้เขียนส่วนขยายได้อย่างรวดเร็ว

  2. โฮสต์ซอร์สโค้ดของส่วนขยายในตำแหน่งที่ตรวจสอบได้แบบสาธารณะ เมื่อโค้ดพร้อมใช้งานจากแหล่งที่มาที่ยืนยันได้ Firebase จะเผยแพร่ส่วนขยายของคุณจากตำแหน่งนี้ได้โดยตรง การทำเช่นนี้จะช่วยให้คุณมั่นใจได้ว่าคุณกำลังเผยแพร่ส่วนขยายเวอร์ชันที่เผยแพร่ล่าสุด และช่วยผู้ใช้ด้วยการอนุญาตให้ตรวจสอบโค้ดที่กำลังจะติดตั้งลงในโปรเจ็กต์

    ปัจจุบันการดำเนินการนี้หมายถึงการทำให้ส่วนขยายพร้อมใช้งานในที่เก็บ GitHub สาธารณะ

  3. อัปโหลดส่วนขยายไปยังฮับส่วนขยายโดยใช้คำสั่ง firebase ext:dev:upload

  4. ไปที่แดชบอร์ดผู้เผยแพร่โฆษณาในคอนโซล Firebase ค้นหาส่วนขยาย ที่คุณเพิ่งอัปโหลด แล้วคลิก "เผยแพร่ไปยังฮับส่วนขยาย" การดำเนินการนี้จะส่งคำขอ ตรวจสอบจากเจ้าหน้าที่ตรวจสอบของเรา ซึ่งอาจใช้เวลา 2-3 วัน หากได้รับอนุมัติ ระบบจะเผยแพร่ส่วนขยายไปยังฮับส่วนขยาย หากถูกปฏิเสธ คุณจะได้รับข้อความอธิบายเหตุผล จากนั้นคุณจะแก้ไขปัญหาที่รายงานและส่งเข้ารับการตรวจสอบอีกครั้งได้