UnityWebRequest (phần 1)

1. UnityWebRequest

   Các UnityWebRequest là một sự thay thế cho đối tượng WWW ban đầu của Unity. Nó cung cấp một hệ thống mô-đun để soạn các HTTP request và xử lý các HTTP response. Mục tiêu chính của hệ thống UnityWebRequest là cho phép game Unity tương tác với các phần phụ trợ Web hiện đại. Nó cũng hỗ trợ các tính năng có nhu cầu cao như các yêu cầu chunked HTTP, streaming hoạt động POST / PUT và toàn quyền kiểm soát các HTTP header và verb.

   Đối với người dùng cuối cùng, những người chỉ sử dụng các trường hợp sử dụng cá nhân thông thường, chuyển sang hệ thống mới nên gần như một quá trình tìm và thay thế. Hệ thống này bao gồm hai lớp. Một API Low-Level (LLAPI) cung cấp sự linh hoạt tối đa cho người sử dụng, trong khi một API cấp cao (HLAPI) wrap API Low-Level và cung cấp một giao diện thuận tiện để thực hiện các hoạt động phổ biến.

2. Architecture

   Các "ecosystem" UnityWebRequest phá vỡ một giao dịch HTTP thành ba hoạt động riêng biệt:

   • Cung cấp dữ liệu cho máy chủ
   • Nhận dữ liệu từ máy chủ
   • kiểm soát flow HTTP (chuyển hướng, xử lý lỗi, vv)

   Để cung cấp một giao diện tốt hơn cho người sử dụng, mỗi hoạt động này mỗi chi phối bởi đối tượng riêng của nó:

   • Một đối tượng UploadHandler xử lý truyền tải dữ liệu đến máy chủ
   • Một đối tượng DownloadHandler xử lý tiếp nhận, đệm và xử lý sau của dữ liệu nhận được từ các máy chủ
   • Một đối tượng UnityWebRequest, trong đó quản lý hai đối tượng khác, và cũng xử lý kiểm soát lưu lượng HTTP. Đối tượng này là nơi tiêu đề tùy chỉnh và URL được xác định, là nơi lỗi và chuyển hướng thông tin được lưu trữ.

   

   Đối với bất kỳ giao dịch HTTP nhất định, dòng mã lệnh tổng quát là:

   • Tạo một đối tượng yêu cầu web
   • Cấu hình các đối tượng yêu cầu web
     • Đặt tiêu đề tùy chỉnh
     • Set HTTP động từ (GET, POST, HEAD, vv)
       • tùy chỉnh verb đã được cấp phép
     • Set URL
   • (Tùy chọn) Tạo Upload Handler và đính kèm nó vào Request Web
     • Cung cấp dữ liệu được tải lên
     • Cung cấp hình thức HTTP để được tải lên
   • (Tùy chọn) Tạo Download Handler và đính kèm nó vào Request Web
   • Gửi Yêu cầu Web
     • Nếu bên trong một coroutine, bạn có thể hạn chế kết quả của Send () để chờ đợi cho các yêu cầu hoàn thành, giống như WWW.
   • (Tùy chọn) Đọc dữ liệu nhận được từ Download Handler
   • (Tùy chọn) Đọc thông tin báo lỗi, mã trạng thái HTTP và response từ các đối tượng UnityWebRequest.

3. Common Opreation: sử dụng HLAPI

   3.1 Nhận Text và Binary Data từ HTTP Server (GET)

   Để lấy dữ liệu đơn giản, chẳng hạn như dữ liệu văn bản hoặc dữ liệu nhị phân, từ một HTTP chuẩn hoặc HTTPS web server, các cuộc gọi để sử dụng là UnityWebRequest.GET. Phương pháp này có string duy nhất như một tham số; string quy định các URL mà từ đó dữ liệu sẽ được lấy ra.

   Phương pháp này là tương tự với các xây dựng WWW tiêu chuẩn:

WWW myWww = new WWW("http://www.myserver.com/foo.txt");
// ... is analogous to ...
UnityWebRequest myWr = UnityWebRequest.Get("http://www.myserver.com/foo.txt");

Cụ thể:

Phương pháp này tạo ra một UnityWebRequest và set URL mục tiêu tới các string argument. Nó đặt ra không có các flag hoặc header tùy chỉnh khác. Theo mặc định, phương pháp này gắn một DownloadHandlerBuffer header đến các UnityWebRequest. xử lý này sẽ đệm dữ liệu nhận được từ máy chủ và làm cho nó có sẵn cho script của bạn khi công việc hoàn tất. Theo mặc định, phương pháp này không gắn UploadHandler đến UnityWebRequest. Bạn có thể đính kèm một manually nếu bạn muốn.

Ví dụ:

using UnityEngine;
using System.Collections;
using UnityEngine.Experimental.Networking;

class MyBehaviour: public MonoBehaviour {
void Start() {
StartCoroutine(GetText());
}

IEnumerator GetText() {
UnityWebRequest www = UnityWebRequest.Get("http://www.my-server.com");
yield return www.Send();

if(www.isError) {
Debug.Log(www.error);
}
else {
// Show results as text
Debug.Log(www.downloadHandler.text);

// Or retrieve results as binary data
byte[] results = www.downloadHandler.data;
}
}
}

3.2 Nhận một texture từ một HTTP Server (GET)

Để lấy một texture từ một remote server, bạn có thể sử dụng UnityWebRequest.Texture. Phương pháp này rất giống với UnityWebRequest.GET, nhưng được tối ưu hóa để tải về và lưu trữ texture hiệu quả. Phương pháp này có một chuỗi duy nhất như là một đối số. Chuỗi xác định các URL mà bạn muốn tải về một tập tin hình ảnh để sử dụng như một texture.

Cụ thể:

Phương pháp này tạo ra một UnityWebRequest và set URL target đến các string argument. Phương pháp này đặt ra không có flag hoặc custom header khác. Phương pháp này gắn một đối tượng DownloadHandlerTexture đến UnityWebRequest. DownloadHandlerTexture là một Download chuyên Handler được tối ưu hóa để lưu trữ hình ảnh mà sẽ được sử dụng như texture trong Engine Unity. Sử dụng lớp này làm giảm đáng kể việc tái phân bổ bộ nhớ so với tải byte dữ liệu và tạo ra một texture bằng tay trong script.

Theo mặc định, phương pháp này gắn vào Upload Handler. Bạn có thể thêm một handler nếu muốn.

Ví dụ:

using UnityEngine;
using System.Collections;
using UnityEngine.Experimental.Networking;

class MyBehaviour: public MonoBehaviour {
    void Start() {
        StartCoroutine(GetTexture());
    }

    IEnumerator GetTexture() {
        UnityWebRequest www = UnityWebRequest.GetTexture("http://www.my-server.com/image.png");
        yield return www.Send();

        if(www.isError) {
            Debug.Log(www.error);
        }
        else {
            Texture myTexture = ((DownloadHandlerTexture)www.downloadHandler).texture;
        }
    }
}

Alternatively, you can implement GetTexture using a helper getter:
    IEnumerator GetTexture() {
        UnityWebRequest www = UnityWebRequest.GetTexture("http://www.my-server.com/image.png");
        yield return www.Send();

        Texture myTexture = DownloadHandlerTexture.GetContent(www);
    }

3.3 Download một Asset Bundle từ HTTP Server (GET)

Để lấy một Asset Bundle từ một remote server, bạn có thể sử dụng UnityWebRequest.AssetBundle. Phương pháp này stream dữ liệu vào một bộ đệm bên trong, mà giải mã / giải nén dữ liệu của Asset Bundle trên một worker thread. Ở dạng đơn giản nhất của nó, nó chỉ mất URL mà từ đó các asset bundle nên được tải về. Bạn có thể tùy chọn cung cấp một checksum để xác minh tính toàn vẹn của dữ liệu tải về.

Cách khác, nếu bạn muốn sử dụng các asset bundle caching system, bạn có thể cung cấp một số version hoặc một cấu trúc dữ liệu Hash128,giống với các version hoặc đối tượng Hash128 cung cấp cho hệ thống cũ qua WWW.LoadFromCacheOrDownload.

Cụ thể:

Phương pháp này tạo ra một UnityWebRequest và set URL target đến các đối số URL được cung cấp. Nó cũng đặt verb HTTP GET, nhưng đặt không có flag hoặc custom header khác. Phương pháp này gắn một DownloadHandlerAssetBundle đến UnityWebRequest, xử lý tải về này có một assetBundle property đặc biệt, có thể được sử dụng để trích xuất các gói tài sản khi đủ dữ liệu đã được tải về và giải mã để cho phép truy cập vào các resource bên trong bó.

Nếu bạn cung cấp một số phiên bản hoặc đối tượng Hash128 như các đối số, nó cũng đi qua những argument tới DownloadHandlerAssetBundle. Việc xử lý tải về sau đó sẽ sử dụng hệ thống bộ nhớ đệm.

Ví dụ:

using UnityEngine;
using System.Collections;

class MyBehaviour: public MonoBehaviour {
    void Start() {
        StartCoroutine(GetAssetBundle());
    }

    IEnumerator GetAssetBundle() {
        UnityWebRequest www = UnityWebRequest.GetAssetBundle("http://www.my-server.com/myData.unity3d");
        yield return www.Send();

        if(www.isError) {
            Debug.Log(www.error);
        }
        else {
            AssetBundle bundle = ((DownloadHandlerAssetBundle)www.downloadHandler).assetBundle;
        }
    }
}

Thay thế, bạn có thể implement GetAssetBundle sử dụng helper getter:

IEnumerator GetTexture() {
    UnityWebRequest www = UnityWebRequest.GetAssetBundle("http://www.my-server.com/myData.unity3d");
    yield return www.Send();

    AssetBundle bundle = DownloadHandlerAssetBundle.GetContent(www);
}