Uso de LAS API REST desde un back-end

2023-05-26

Como se explica en Administración de registros, normalmente el back-end de la aplicación envía notificaciones y puede realizar la administración de registros. Dado que ya hay un contenedor REST para Node.js en el SDK de Azure para Node, en esta sección se muestran ejemplos en Java.

Enviar notificaciones

La API REST para enviar notificaciones es una publicación simple en /yourHub/messages, con encabezados especiales. Al enviar notificaciones en un formato nativo de la plataforma, el cuerpo es el cuerpo específico de la plataforma que se va a enviar. Los encabezados adicionales son:

ServiceBusNotification-Format: especifica que la plataforma (si envía una notificación nativa) o "plantilla" es enviar una notificación de plantilla.
ServiceBusNotification-Tags (opcional): especifica la etiqueta (o expresión de etiqueta) que define el conjunto de registros de destino. Si este encabezado no está presente, el centro de notificaciones transmite a todos los registros.

Otros encabezados son compatibles con la funcionalidad específica de la plataforma, como se especifica en la documentación de las API REST de Notification Hubs .

El código Java siguiente envía una notificación nativa a las aplicaciones de la Tienda Windows (mediante 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();
    }
}

Del mismo modo, el código siguiente envía una notificación de plantilla:

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;
}

Para obtener más información sobre cómo enviar notificaciones a otras plataformas, consulte API REST de Notification Hubs.

Creación y actualización de registros

La creación y actualización de registros requiere la serialización y deserialización del formato XML de registro. En el tema Crear una API de registro se muestran los formatos XML para crear diferentes tipos de registros (nativos y de plantilla para cada plataforma).

Importante

Los elementos XML deben estar en el orden exacto que se muestra.

A continuación se muestra un ejemplo de creación de un registro en Java, mediante concatenaciones de cadenas simples para crear la carga XML de registro y Apache Digester para analizar el resultado. Como se indicó anteriormente, cualquier enfoque de serialización o deserialización XML funciona.

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();
    }
}

El método getXml() para los registros nativos de Windows es el siguiente:

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();
}

Puede derivar fácilmente los métodos para otros tipos de registro de los ejemplos del tema Creación de una API de registro.

La respuesta contiene el resultado de la creación, incluidas las propiedades de solo lectura, como RegistrationId, ETag y ExpirationTime. En el ejemplo de código siguiente se analiza el resultado mediante 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);
}

La llamada Create devuelve un registrationId, que se usa para recuperar, actualizar o eliminar el registro.

Nota:

En el fragmento de código anterior se supone que hay una subclase de Registration denominada WindowsRegistrationDescription.

Para actualizar un registro, emita una llamada PUT en /yourhub/registrations/{registrationId}. El encabezado If-Match se usa para proporcionar una ETag (compatibilidad con la simultaneidad optimista) o simplemente un "*" para sobrescribir siempre. Si el encabezado If-Match no está presente, la operación realiza una "upsert" (siempre sobrescribe el registro actual o crea uno en el registrationId proporcionado si no está presente). Por ejemplo:

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();
    }
}

Eliminar un registro es una operación similar.

Recuperación de registros

Al recuperar un registro, emita una llamada GET en /registrations/{registrationId}. Recupera una colección de registros tal como se especifica en las siguientes API REST:

A continuación, tiene la opción de especificar un parámetro $top , que limita el número de registros devueltos. Si hay más registros presentes para esa consulta, se devuelve un encabezado X-MS-ContinuationToken , que puede pasar a llamadas posteriores para continuar recuperando los registros restantes. Tenga en cuenta también que el formato del cuerpo ahora es una fuente Atom XML, como se muestra en los temas de API mencionados anteriormente.

El código Java siguiente de minterastlib recupera todos los registros con una etiqueta;

    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();
        }
    }

En este código, collectionResult encapsula un conjunto de registros junto con un token de continuación opcional.

El código siguiente usa 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);
}

Compartir a través de

Uso de LAS API REST desde un back-end

Enviar notificaciones

Creación y actualización de registros

Recuperación de registros

Recursos adicionales