การรับสถานะของวิดีโอด้วย Webhook

เพื่อให้ระบบภายนอกรับทราบสถานะล่าสุดของการอัปโหลดและประมวลผลวิดีโอภายใน ByteArk Stream นอกจากการ Poll API เพื่อดึงสถานะของวิดีโอเป็นระยะๆ แล้ว นักพัฒนาสามารถใช้ฟีเจอร์ Webhook เพื่อรับสถานะการประมวลผลล่าสุดของวิดีโอ โดยระบบ ByteArk Stream จะส่งสถานะของแต่ละวิดีโอผ่าน HTTP Post ไปยังเซิร์ฟเวอร์ภายนอก เมื่อวิดีโอมีการสร้าง อัปโหลด และพร้อมรับชมได้ ช่วยให้นักพัฒนาสามารถสร้างระบบวิดีโอที่มีการอัพเดตสถานะของวิดีโอในระบบภายในอกได้ทันทีที่มีการอัปโหลดและพร้อมรับชม

ประเภทของ Event ที่ส่งจาก Webhook

• Source waiting : วิดีโอได้ถูกสร้างขึ้นแล้ว กำลังรอรับไฟล์
• Source ingression : ไฟล์วิดีโอต้นฉบับถูกอัปโหลดเสร็จสิ้นแล้ว กำลังรอตรวจสอบข้อมูล
• Processing : งานประมวผลวิดีโอได้เข้าสู่คิวและกำลังประมวลผล
• Partially completed : วิดีโอประมวลผลเสร็จอย่างน้อยหนึ่งความละเอียด สามารถรับชมในเบื้องต้นได้
• Completed : วิดีโอถูกประมวลผลเสร็จสิ้นทุก พร้อมรับชมทุกความละเอียด
• Updated : มีการอัพเดตข้อมูลของวิดีโอผ่านหน้าเว็บหรือ API ของ ByteArk Stream

การพัฒนาระบบเพื่อรับ Webhook

เมื่อมี Event เกิดขึ้น ระบบ ByteArk Stream จะส่ง HTTP Post ในรูปแบบ JSON ที่ประกอบด้วยข้อมูลต่อไปนี้ไปยังเซิร์ฟเวอร์ภายนอก โดยมีข้อมูลที่สำคัญดังนี้

• eventName : ประเภทของ Event
• payload : ข้อมูลของวิดีโอที่มีการอัพเดตสถานะ โดยมีรายชื่อคีย์ที่สำคัญดังนี้
• payload.videoKey : เป็น Key ของวิดีโอที่ใช้อ้างอิงถึงวิดีโอในระบบ
• payload.videoTitle ซึ่งเป็นชื่อของไฟล์วิดีโอที่อยู่ในระบบ
• payload.createdAt : เวลาที่มีการสร้างวิดีโอ ทั้งนี้ข้อมูลวิดีโอจะถูกส่งออกมาเป็น JSON Object ของวิดีโอที่มีข้อมูลอื่นๆ ให้นักพัฒนาสามารถอ่านค่าได้ด้วย อ้างอิงตามตัวอย่าง Request ท้ายเอกสาร

นักพัฒนาจะต้องเตรียม HTTP Endpoint ที่สามารถรับ Post Method แล้วอ่านข้อมูล JSON ในรูปแบบดังกล่าว แล้วให้ระบบภายนอกอัพเดตสถานะของวิดีโอตาม VideoKey ที่ส่งมาได้ ตัวอย่างเช่น

• เมื่อได้รับสถานะ Source waiting ของวิดีโอ ให้สร้างวิดีโอขึ้นในระบบแต่ยังไม่ได้อยู่ในสถานะให้พร้อมรับชมกับคนทั่วไป
• เมื่อได้รับสถานะ Completed ของวิดีโอ ให้ปรับการแสดงผลว่าวิดีโอพร้อมรับกับคนทั่วไปได้

การเปิดใช้งานคุณสมบัติ Webhook

หลังจากเข้าสู่หน้าโปรเจคแล้ว ให้เข้าสู่เมนู Manage Project -> Webhooks แล้วกด New Webhook เพื่อสร้างการตั้งค่า Webhook ที่รายงานผลไปยังเซิร์ฟเวอร์ภายนอก โดยในการตั้งค่าให้ระบุข้อมูลที่สำคัญดังนี้

• Name : ชื่อของ Webhook
• URL : URL HTTP Endpoint ที่จะรับ Webhook
• Secret Key : สำหรับใช้ยืนยันตัวตนข้อมูลระหว่างระบบ โดยจะส่งออกใน HTTP Header ชื่อ X-Byteark-Hooks

หลังจากสร้างการตั้งค่าดังกล่าวแล้ว นักพัฒนาสามารถทดสอบการรับ Webhook ด้วยเมนู Test Webhook เพื่อส่งค่าทดสอบออกจากระบบได้ และสามารถติดตามสถานะการส่ง Webhook ของระบบในหน้า Event Logs ได้

อ้างอิงตัวอย่าง POST Request จาก Webhook

{
  "eventName": "byteark.stream.video.completed",
  "payload": {
    "videoKey": "GdEZzGoiMIhe",
    "video": {
      "geoblockPolicy": {
        "appliedRule": {
          "allowCountryCodes": [],
          "denyCountryCodes": []
        },
        "type": "existingRule",
        "name": "รับชมได้ทุกประเทศ",
        "ruleId": "114d5df373cefb69977e1ac7"
      },
      "key": "GdEZzGoiMIhe",
      "title": "ชื่อวิดีโอ.mp4",
      "subtitle": null,
      "description": null,
      "duration": 3463.217,
      "channelName": null,
      "tagIds": [],
      "projectId": "555575ff21c6f05c14da582f",
      "accessControlPolicyId": null,
      "creatorId": "555bbbbe5c100e2fee6d97f9",
      "hostingId": "55525c7cbf465eeab01812f7",
      "playableAt": "2023-05-02T05:34:43.632Z",
      "playerId": "5555c526693e00215db86ea",
      "playbackChannelIds": [
        "55555c526693e00215db86f5"
      ],
      "primaryPlaybackChannelId": "55555c526693e00215db86f5",
      "customImageEntries": [],
      "deleted": false,
      "customFieldEntries": [
        {
          "fieldId": "55557252fbdfe130749d12d1",
          "type": "text",
          "textValue": "38894",
          "field": {
            "type": "text",
            "fieldName": "requestId",
            "displayName": "requestId",
            "id": "55557252fbdfe130749d12d1"
          }
        },
      ],
      "vodId": "5555992e3937eac295c9be92",
      "createdAt": "2023-05-02T05:01:34.761Z",
      "updatedAt": "2023-05-02T05:34:43.633Z",
      "coverImage": {
        "sizes": {
          "small": "https://stream-image.byteark.com/image/video-cover-144p/7/H/7XXXzHTyV.png",
          "medium": "https://stream-image.byteark.com/image/video-cover-480p/7/H/7XXXzHTyV.png",
          "large": "https://stream-image.byteark.com/image/video-cover-1080p/7/H/7XXXzHTyV.png"
        },
        "mediaServerType": "imgproxy"
      },
      "playable": true,
      "vod": {
        "processingInfo": {
          "state": "completed",
          "totalCompletedOutputs": 2,
          "totalExpectedOutputs": 2
        },
        "sourceId": "5555992e3937eac295c9be89",
        "storageId": "555511052a8a5b28fa0ddd0f",
        "presetId": "555593c3f39a395a1d79a897",
        "outputs": [
          {
            "size": 480,
            "resolutionType": "scaleByShorterSide",
            "width": 640,
            "height": 480,
            "displayAspectRatio": "4:3",
            "frameRate": "60/1",
            "audioGroupId": null,
            "_id": "6450a0f3db27c3e4e59245ae",
            "type": "video",
            "formatType": "hls",
            "storageId": "644611052a8a5b28fa0ddd0f",
            "trackKey": "XXXXSugK",
            "name": "480p",
            "path": "assets/xxx-transcode-video/media/XXXXX-xxx-production-xxxnz9/T/d/4/XXXXXGoiMIbe-Td4ZzH85msRo/hls/XXXXSugK/480p/prog_index.m3u8",
            "version": 0,
            "codecsParameter": "avc1.4d401f,mp4a.40.2",
            "fileSize": 186999088,
            "bitRate": 431967
          },
          {
            "size": 240,
            "resolutionType": "scaleByShorterSide",
            "width": 320,
            "height": 240,
            "displayAspectRatio": "4:3",
            "frameRate": "60/1",
            "audioGroupId": null,
            "_id": "6450b7c8db27c3e4e5933d09",
            "type": "video",
            "formatType": "hls",
            "storageId": "644611052a8a5b28fa0ddd0f",
            "trackKey": "XXXXSuyg",
            "name": "240p",
            "path": "assets/xxx-transcode-video/media/XXXXX-xxx-production-xxxnz9/T/d/4/XXXXXGoiMIbe-Td4ZzH85msRo/hls/XXXXSuyg/240p/prog_index.m3u8",
            "version": 0,
            "codecsParameter": "avc1.4d401f,mp4a.40.2"
          }
        ],
        "videoId": "6450992e3937eac295c9be87",
        "startPts": 0,
        "revisionKey": "XXXXXH85msRo",
        "submittedAt": "2023-05-02T05:01:35.676Z",
        "playableAt": "2023-05-02T05:34:43.632Z",
        "sourceAvailabledAt": "2023-05-02T05:01:35.676Z",
        "playbackFormats": [
          "hls"
        ],
        "captions": [],
        "storyboards": [],
        "createdAt": "2023-05-02T05:01:34.755Z",
        "updatedAt": "2023-05-02T07:12:08.325Z",
        "playable": true,
        "uploadable": true,
        "id": "6450992e3937eac295c9be92"
      },
      "embeddedUrl": "https://stream-player.byteark.com/players/63525c526693e00215db86ea/videos/XXXXXGoiMIbe",
      "id": "6450992e3937eac295c9be87",
      "playbackUrls": [
        {
          "name": "XXXXXtksz5h9",
          "hls": [
            {
              "name": "Adaptive Bitrate",
              "url": "https://XXXXXtksz5h9.stream-playlist.byteark.com/streams/XXXXXGoiMIbe/playlist.m3u8"
            },
            {
              "name": "Adaptive Bitrate",
              "url": "https://XXXXXtksz5h9.stream-playlist-internal.ark.farm/streams/XXXXXGoiMIbe/playlist.m3u8"
            }
          ]
        }
      ],
      "primaryPlaybackUrl": {
        "name": "XXXXXtksz5h9",
        "hls": [
          {
            "name": "Adaptive Bitrate",
            "url": "https://XXXXXtksz5h9.stream-playlist.byteark.com/streams/XXXXXGoiMIbe/playlist.m3u8"
          },
          {
            "name": "Adaptive Bitrate",
            "url": "https://XXXXXtksz5h9.stream-playlist-internal.ark.farm/streams/XXXXXGoiMIbe/playlist.m3u8"
          }
        ]
      },
      "simpleCustomImageFields": {},
      "customFields": {
        "requestId": "38894",
        "fieldName": "custom1"
      },
      "simpleCustomFields": {
        "requestId": "38894",
        "fieldName": "custom2"
      }
    }
  }
}