Menggunakan REST API dari backend

2023-05-26

Seperti yang dijelaskan dalam Manajemen pendaftaran, biasanya back-end aplikasi mengirim pemberitahuan dan mungkin melakukan manajemen pendaftaran. Karena sudah ada pembungkus REST untuk Node.js di Azure SDK for Node, bagian ini menunjukkan contoh di Java.

Mengirim pemberitahuan

REST API untuk mengirim pemberitahuan adalah POST sederhana di /yourHub/messages, dengan header khusus. Saat mengirim pemberitahuan dalam format asli platform, isinya adalah isi khusus platform yang akan dikirim. Header tambahan adalah:

ServiceBusNotification-Format: Menentukan bahwa platform (jika mengirim pemberitahuan asli) atau "templat" adalah mengirim pemberitahuan templat.
ServiceBusNotification-Tags (opsional): Menentukan tag (atau ekspresi tag) yang menentukan set pendaftaran yang ditargetkan. Jika header ini tidak ada, hub pemberitahuan disiarkan ke semua pendaftaran.

Header lain didukung untuk fungsionalitas khusus platform, seperti yang ditentukan dalam dokumentasi NOTIFICATION Hubs REST API .

Kode Java berikut mengirimkan pemberitahuan asli ke aplikasi Windows Store (menggunakan Apache HttpClient):

public Notification createWindowsNotification(String body) {
    Notification n = new Notification();
    n.body = body;

    n.headers.put("ServiceBusNotification-Format", "windows");

    if (body.contains("<toast>"))
        n.headers.put("X-WNS-Type", "wns/toast");
    if (body.contains("<tile>"))
        n.headers.put("X-WNS-Type", "wns/tile");
    if (body.contains("<badge>"))
        n.headers.put("X-WNS-Type", "wns/badge");

    if (body.startsWith("<")) {
        n.contentType = ContentType.APPLICATION_XML;
    }

    return n;
}

public void sendNotification(Notification notification, String tagExpression) {
    HttpPost post = null;
    try {
        URI uri = new URI(endpoint + hubPath + "/messages"+APIVERSION);
        post = new HttpPost(uri);
        post.setHeader("Authorization", generateSasToken(uri));

        if (tagExpression != null && !"".equals(tagExpression)) {
            post.setHeader("ServiceBusNotification-Tags", tagExpression);
    }

        for (String header: notification.getHeaders().keySet()) {
            post.setHeader(header, notification.getHeaders().get(header));
        }

        post.setEntity(new StringEntity(notification.getBody()));
        HttpResponse response = httpClient.execute(post);

        if (response.getStatusLine().getStatusCode() != 201) {
            String msg = "";
            if (response.getEntity() != null && response.getEntity().getContent() != null) {
                msg = IOUtils.toString(response.getEntity().getContent());
            }
            throw new RuntimeException("Error: " + response.getStatusLine() + " body: "+msg);
        }
    } catch (Exception e) {
        throw new RuntimeException(e);
    } finally {
        if (post != null) post.releaseConnection();
    }
}

Demikian pula, kode berikut mengirimkan pemberitahuan templat:

public Notification createTemplateNotification(Map<String, String> properties) {
    Notification n = new Notification();
    StringBuffer buf = new StringBuffer();
    buf.append("{");
    for (Iterator<String> iterator = properties.keySet().iterator(); iterator.hasNext();) {
        String key = iterator.next();
        buf.append("\""+ key + "\":\""+properties.get(key)+"\"");
        if (iterator.hasNext()) buf.append(",");
    }
    buf.append("}");
    n.body = buf.toString();

    n.contentType = ContentType.APPLICATION_JSON;

    n.headers.put("ServiceBusNotification-Format", "template");

    return n;
}

Untuk informasi selengkapnya tentang mengirim pemberitahuan ke platform lain, lihat NOTIFICATION Hubs REST API.

Membuat dan memperbarui pendaftaran

Membuat dan memperbarui pendaftaran memerlukan serialisasi dan deserialisasi format XML pendaftaran. Topik Buat API pendaftaran menunjukkan format XML untuk membuat berbagai jenis pendaftaran (asli dan templat untuk setiap platform).

Penting

Elemen XML harus dalam urutan yang tepat yang ditunjukkan.

Berikut ini adalah contoh pembuatan pendaftaran di Java, menggunakan perangkaian string sederhana untuk membuat payload XML pendaftaran, dan Apache Digester untuk mengurai hasilnya. Seperti yang disebutkan sebelumnya, pendekatan serialisasi XML atau deserialisasi apa pun berfungsi.

public Registration createRegistration(Registration registration) {
    HttpPost post = null;
    try {
        URI uri = new URI(endpoint + hubPath + "/registrations"+APIVERSION);
        post = new HttpPost(uri);
        post.setHeader("Authorization", generateSasToken(uri));

        StringEntity entity = new StringEntity(registration.getXml(),ContentType.APPLICATION_ATOM_XML);
        entity.setContentEncoding("utf-8");
        post.setEntity(entity);
        HttpResponse response = httpClient.execute(post);

        if (response.getStatusLine().getStatusCode() != 200)
            throw new RuntimeException("Error: " + response.getStatusLine());

        return Registration.parse(response.getEntity().getContent());
    } catch (Exception e) {
        throw new RuntimeException(e);
    } finally {
        if (post != null) post.releaseConnection();
    }
}

Metode getXml() untuk pendaftaran Windows asli adalah sebagai berikut:

private static final String WNS_NATIVE_REGISTRATION = "<?xml version=\"1.0\" encoding=\"utf-8\"?><entry xmlns=\"http://www.w3.org/2005/Atom\"><content type=\"application/xml\"><WindowsRegistrationDescription xmlns:i=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns=\"http://schemas.microsoft.com/netservices/2010/10/servicebus/connect\">{0}<ChannelUri>{1}</ChannelUri></WindowsRegistrationDescription></content></entry>";

public String getXml() {
    String xml = WNS_NATIVE_REGISTRATION.replaceFirst("\\{1\\}", channelUri.toString());
    xml = xml.replaceFirst("\\{0\\}", getTagsXml());
    return xml.toString();
}

Anda dapat dengan mudah memperoleh metode untuk jenis pendaftaran lain dari contoh dalam topik Buat API pendaftaran .

Respons berisi hasil pembuatan, termasuk properti baca-saja seperti RegistrationId, ETag, dan ExpirationTime. Contoh kode berikut mengurai hasilnya menggunakan Apache Digester:

public static Registration parse(InputStream content) throws IOException,
            SAXException {
    Digester digester = new Digester();
    digester.addObjectCreate("*/WindowsRegistrationDescription",
                WindowsRegistration.class);

    digester.addCallMethod("*/RegistrationId", "setRegistrationId", 1);
    digester.addCallParam("*/RegistrationId", 0);
    digester.addCallMethod("*/ETag", "setEtag", 1);
    digester.addCallParam("*/ETag", 0);
    digester.addCallMethod("*/ChannelUri", "setChannelUri", 1);
    digester.addCallParam("*/ChannelUri", 0);
    digester.addCallMethod("*/Tags", "setTagsFromString", 1);
    digester.addCallParam("*/Tags", 0);
    digester.addCallMethod("*/BodyTemplate", "setBodyTemplate", 1);
    digester.addCallParam("*/BodyTemplate", 0);
    digester.addCallMethod("*/WnsHeader", "addHeader", 2);
    digester.addCallParam("*/WnsHeader/Header", 0);
    digester.addCallParam("*/WnsHeader/Value", 1);

    return digester.parse(content);
}

Panggilan Buat mengembalikan registrationId, yang digunakan untuk mengambil, memperbarui, atau menghapus pendaftaran.

Catatan

Cuplikan sebelumnya mengasumsikan bahwa ada subkelas Pendaftaran yang disebut WindowsRegistrationDescription.

Anda dapat memperbarui pendaftaran dengan mengeluarkan panggilan PUT di /yourhub/registrations/{registrationId}. Header If-Match digunakan untuk menyediakan ETag (mendukung konkurensi optimis) atau hanya "*" untuk selalu menimpa. Jika header If-Match tidak ada, operasi melakukan "upsert" (selalu menimpa pendaftaran saat ini, atau membuatnya pada registrationId yang disediakan jika tidak ada). Contohnya:

public Registration updateRegistration(Registration registration) {
    HttpPut put = null;
    try {
        URI uri = new URI(endpoint + hubPath + "/registrations/"+registration.getRegistrationId()+APIVERSION);
        put = new HttpPut(uri);
        put.setHeader("Authorization", generateSasToken(uri));
        put.setHeader("If-Match", registration.getEtag()==null?"*":"W/\""+registration.getEtag()+"\"");

        put.setEntity(new StringEntity(registration.getXml(),ContentType.APPLICATION_ATOM_XML));
        HttpResponse response = httpClient.execute(put);

        if (response.getStatusLine().getStatusCode() != 200)
            throw new RuntimeException("Error: " + response.getStatusLine());

        return Registration.parse(response.getEntity().getContent());
    } catch (Exception e) {
        throw new RuntimeException(e);
    } finally {
        if (put != null) put.releaseConnection();
    }
}

Menghapus pendaftaran adalah operasi serupa.

Mengambil pendaftaran

Saat mengambil pendaftaran, terbitkan panggilan GET pada /registrations/{registrationId}. Anda mengambil kumpulan pendaftaran seperti yang ditentukan dalam REST API berikut:

Anda kemudian memiliki opsi untuk menentukan parameter $top , yang membatasi jumlah pendaftaran yang dikembalikan. Jika ada lebih banyak pendaftaran untuk kueri tersebut, header X-MS-ContinuationToken dikembalikan, yang dapat Anda lewati ke panggilan berikutnya untuk terus mengambil pendaftaran yang tersisa. Perhatikan juga bahwa format isi sekarang menjadi umpan Atom XML, seperti yang ditunjukkan dalam topik API yang disebutkan sebelumnya.

Kode Java berikut dari minterastlib mengambil semua pendaftaran dengan tag;

    private CollectionResult retrieveRegistrationByTag() {
        String queryUri = endpoint + hubPath + "/tags/"+tag+"/registrations"+APIVERSION;
    HttpGet get = null;
        try {
            URI uri = new URI(queryUri);
            get = new HttpGet(uri);
            get.setHeader("Authorization", generateSasToken(uri));
    
            HttpResponse response = httpClient.execute(get);
    
            if (response.getStatusLine().getStatusCode() != 200)
                throw new RuntimeException("Error: " + response.getStatusLine());
    
            CollectionResult result = Registration.parseRegistrations(response.getEntity().getContent());
            Header contTokenHeader = response.getFirstHeader("X-MS-ContinuationToken");
            if (contTokenHeader !=null) {
                result.setContinuationToken(contTokenHeader.getValue());
            }
            return result;
        } catch (Exception e) {
            throw new RuntimeException(e);
        } finally {
            if (get != null) get.releaseConnection();
        }
    }

Dalam kode ini, CollectionResult merangkum serangkaian pendaftaran bersama dengan token kelanjutan opsional.

Kode berikut menggunakan Apache Digester:

public static CollectionResult parseRegistrations(InputStream content)
            throws IOException, SAXException {
    Digester digester = new Digester();

    // add all rules for parsing single registrations
    digester.addObjectCreate("feed", CollectionResult.class);
    digester.addSetNext("*/WindowsRegistrationDescription", "addRegistration");
    // add rules for other types of registrations (if required)

    return digester.parse(content);
}

Bagikan melalui

Menggunakan REST API dari backend

Mengirim pemberitahuan

Membuat dan memperbarui pendaftaran

Mengambil pendaftaran

Sumber Daya Tambahan: