Entwicklung des mobilen Messagings (Übersicht)

Artikel
09/24/2014

Letzte Änderung: Mittwoch, 14. April 2010

Gilt für: SharePoint Foundation 2010

Dieses Thema liefert einen Überblick über das Hinzufügen von Funktionalität für mobiles Messaging zu einem Microsoft SharePoint Foundation-Entwicklungsprojekt mithilfe der Anwendungsprogrammierschnittstellen (Application Programming Interfaces, APIs) für mobiles Messaging des SharePoint Foundation Software Development Kit (SDK). Diese APIs können in zwei große Gruppen unterteilt werden: APIs, die SMS-Nachrichten (Short Message Service) mithilfe des OMS-Kommunikationsprotokolls (Office Mobile Service) unterstützen, und APIs, mit denen Sie die Unterstützung für andere Kommunikations- oder Nachrichtenstrukturprotokolle ermöglichen. Bei den meisten Entwicklungsszenarien ist der Absender der Nachrichten die SharePoint Foundation-Webanwendung, und kein bestimmter Benutzer. Deshalb ist für die SharePoint Foundation-Bereitstellung ein Konto bei einem Dienstanbieter für mobiles Messaging (Mobile Messaging Service Provider, MSP) erforderlich, der das von Ihrer Lösung verwendete Kommunikationsprotokoll unterstützt.

Das OMS-Protokoll (Office Mobile Service) ist ein Kommunikationsprotokoll mit einer Implementierung der Nachrichtenstrukturprotokolle SMS und MMS (Multimedia Message Service). OMS erfordert das SOAP-Protokoll für den Webdienstzugriff. Die im folgenden Abschnitt OMS-SMS-Messaginglösungen behandelten APIs mit OMS-Unterstützung wurden für SMS-Nachrichten entwickelt. Klassen oder Member im Microsoft.SharePoint.MobileMessage-Namespace, die "MMS" im Namen aufweisen oder die nur im Zusammenhang mit MMS-Nachrichten Sinn ergeben, sind nur für die interne Verwendung gedacht und sollten nicht im Code aufgerufen werden. Verwenden Sie zum Entwickeln von Messaginglösungen, die nicht OMS als Kommunikationsprotokoll verwenden oder die OMS für MMS-Nachrichten verwenden, die weiter unten im Abschnitt Entwickeln für andere Protokolle behandelten abstrakteren APIs.

OMS-SMS-Messaginglösungen

In SharePoint Foundation gibt es APIs, mit denen alle OMS-Webmethodenaufrufe und alle XML-Analysen und -Schreibvorgänge für Sie ausgeführt werden. Die APIs werden vom Code einfach in vertrauter, objektorientierter Syntax aufgerufen.

Erstellen eines Kontos bei einem Dienstanbieter für mobiles Messaging für eine Webanwendung

Für jede SharePoint Foundation-Webanwendung, einschließlich der Webanwendung für die Zentraladministration, ist ein Konto bei einem Dienstanbieter für mobiles Messaging (Mobile Messaging Service Provider, MSP) möglich. Normalerweise werden diese Konten in der Zentraladministrationsanwendung unter Anwendungsverwaltung von einem Farmadministrator festgelegt. Sie können jedoch ein Konto programmgesteuert erstellen und einer Webanwendung zuweisen. Rufen Sie zunächst einen SPMobileMessagingAccount()-Konstruktor auf, der keinen SPMobileMessageServiceProvider-Parameter erfordert. Anschließend rufen Sie die UpdateSmsAccount(SPMobileMessagingAccount)-Methode auf, um das Konto einer Webanwendung zuzuweisen. Im folgenden Codeausschnitt stellt webApp einen Verweis auf ein SPWebApplication -Objekt dar. (Informationen zum Abrufen eines Verweises auf ein solches Objekt finden Sie unter Abrufen von Verweisen auf Websites, Webanwendungen und andere Schlüsselobjekte). Bei diesem Codeausschnitt wird davon ausgegangen, dass die Datei using Anweisungen für Microsoft.SharePoint und System.Security enthält. Beachten Sie, dass der Aufruf von UpdateSmsAccount(SPMobileMessagingAccount) im Rahmen eines anonymen Delegaten an die RunWithElevatedPrivileges(SPSecurity.CodeToRunElevated)-Methode übergeben wird.

SecureString password = new SecureString();
password.AppendChar(‘a’);
password.AppendChar(‘Z’);
password.AppendChar(‘3’);
password.AppendChar(‘&’);

SPMobileMessagingAccount account = new SPMobileMessagingAccount("Contoso Messaging",
                                                                "https://contoso.com/services/mobilemessages",
                                                                 "BobG",
                                                                 password);

SPSecurity.RunWithElevatedPrivileges(delegate() {webApp.UpdateSmsAccount(account);
                                                 webApp.Update();});

Dim password As New SecureString()
        password.AppendChar("a")
        password.AppendChar("z")
        password.AppendChar("3")
        password.AppendChar("&")

        Dim account As New SPMobileMessagingAccount("Contoso Messaging", "https://contoso.com/services/mobilemessages", "BobG", password)


        SPSecurity.RunWithElevatedPrivileges(Sub()
                                                 webApp.UpdateSmsAccount(account)
                                                 webApp.Update()
                                             End Sub)

Nachdem der Webanwendung ein Konto bei einem Dienstanbieter für mobiles Messaging zugewiesen wurde, können Sie danach die OutboundSmsServiceAccount-Eigenschaft im Code als Verweis auf das Kontoobjekt der Webanwendung verwenden.

Erstellen eines Webdienstobjekts

Wenn Sie über ein SPMobileMessagingAccount-Objekt verfügen, kann damit im Code ein SPMobileMessageWebService-Objekt erstellt werden, das die Methoden zum Senden von SMS-Nachrichten enthält. Wenn Sie einen Verweis auf ein permanentes SPMobileMessagingAccount-Objekt erhalten, sollten Sie stets überprüfen, dass es nicht null ist und dass die IsValidAccount()-Eigenschaft true ist. Der folgende Codeausschnitt veranschaulicht, wie Sie ein Webdienstobjekt erstellen. Bei webApp handelt es sich um einen Verweis auf ein SPWebApplication-Objekt.

SPMobileMessagingAccount account = webApp.OutboundSmsServiceAccount;
if (account == null || !account.IsValidAccount())
{
    throw new SPException("The account passed in is invalid.");
}
else
{
    SPMobileMessageWebService messagingWebService = new SPMobileMessageWebService(account);
}

Dim account As SPMobileMessagingAccount = webApp.OutboundSmsServiceAccount
If account Is Nothing OrElse (Not account.IsValidAccount()) Then
    Throw New SPException("The account passed in is invalid.")
Else
    Dim messagingWebService As New SPMobileMessageWebService(account)
End If

Verfassen und Senden einer SMS-Nachricht

Das Verfassen und das Senden der Nachricht sind die nächsten beiden wichtigen Aufgaben.

Verfassen einer Nachricht

Mit einem SPMobileMessageWebService-Objekt können mit dem Code die OMS-Webmethoden des Diensts aufgerufen werden, indem Sie die Methoden des Objekts als Proxys verwenden. Die wichtigste Methode ist natürlich die SendMessage(String)-Methode. Bevor Sie diese aufrufen können, muss jedoch zuerst die Nachricht im Code verfasst werden. Hierfür gibt es drei Methoden.

Mit dem Code kann die statische BuildSmsMessage(SPMobileMessagingAccount, String, String)-Methode aufgerufen werden, und es können Parameter für das Konto des Absenders, ein Empfänger und der Nachrichtentext an diese Methode übergeben werden. Dies ist die einfachste, aber am wenigsten flexible Vorgehensweise.
Mit dem Code kann eine der Überladungen von SetTextContent() aufgerufen werden. Dazu müssten Sie zuerst das SPMobileMessageSmsBuilder-Objekt erstellen und Empfänger durch Aufrufen der AddRecipient(String)-Methode hinzufügen. Außerdem müssten Sie die Nachricht von dem SPMobileSmsMessage-Objekt, das von SetTextContent() erstellt wird, in das entsprechende Nachrichten-XML des OMS-Protokolls konvertieren. Bei dieser Vorgehensweise zum Verfassen der Nachricht sind mehrere Empfänger möglich. Außerdem können Sie einen niedrigeren Grenzwert als den vom Dienstanbieter festgelegten Grenzwert (ContentParts) für die Anzahl von untergeordneten Seiten festlegen, in die die Nachricht aufgeteilt wird, falls der Nachrichtentext den Zeichengrenzwert des Diensts überschreitet.
Mit dem Code kann eine Transaktion zum Verfassen von Nachrichten erstellt werden. Eine solche Transaktion setzt sich wie folgt zusammen:
1. Ein Aufruf von StartTextMessage()
2. Einer oder mehrere Aufrufe von AddChunk(String)
3. Ein Aufruf einer der Überladungen von EndTextMessage()
Diese Vorgehensweise zum Verfassen der Nachricht beinhaltet wie die vorherige Vorgehensweise alle Möglichkeiten sowie Komplikation. Darüber hinaus haben Sie jedoch mehr Kontrolle darüber, wie die Nachricht in Seiten aufgeteilt wird, und außerdem verfügen Sie über zusätzliche Möglichkeiten, wie z. B. das Hinzufügen von Seitenzahlen.

Wenn eine Nachricht den Grenzwert des Dienstanbieters für die Anzahl von Zeichen überschreitet, versucht der Nachrichtenerstellungsalgorithmus unabhängig von der verwendeten Methode, die Nachricht in mehrere Nachrichten aufzuteilen, indem sie zwischen "Textabschnitten" geteilt wird. Ein Textabschnitt besteht aus Zeichen, die möglichst in einer einzigen Nachrichten zusammengehalten werden sollten. Dadurch ist die resultierende Abfolge von Nachrichten zusammenhängender, als wenn die übergeordnete Nachricht in gleiche, aber willkürliche Teile aufgeteilt würden. Falls ein bestimmter Textabschnitt selbst den Zeichengrenzwert überschreitet, wird er dennoch geteilt. Nur mit der dritten Methode zum Verfassen einer Nachricht bietet der Code eine gewisse Kontrolle darüber, wie die Nachricht in Textabschnitte geteilt wird. Im folgenden Codeausschnitt wird die dritte Methode veranschaulicht. Beachten Sie bei diesem Beispiel Folgendes:

account ist ein Verweis auf ein SPMobileMessagingAccount-Objekt.
Obwohl nur ein Aufruf von AddRecipient(String) vorhanden ist, sind mehrere Aufrufe möglich, um dieselbe Nachricht an mehrere Empfänger zu senden, bis zum Erreichen des vom Dienstanbieter für mobiles Messaging festgelegten Grenzwerts.
SplitLongMessage ist im nächsten Codeabschnitt darunter definiert.
message ist ein String-Objekt, das die Nachricht enthält.
Wenn die Transaktion zum Verfassen der Nachricht abgeschlossen ist, enthält das SPMobileMessageSmsBuilder-Objekt die Nachricht in der Message-Eigenschaft.

SPMobileMessageSmsBuilder smsBuilder = new SPMobileMessageSmsBuilder(account);
smsBuilder.AddRecipient(mobile_telephone_number);

// Begin the message building transaction
smsBuilder.StartTextMessage();

// Add the message text, split as needed into chunks.
List<StringBuilder> messageParts = SplitLongMessage(message)
foreach (StringBuilder chunk in messageParts)
{
    smsBuilder.AddChunk(chunk.ToString());
}

// Finish the transaction
smsBuilder.EndTextMessage();

// At this point, the smsBuilder.Message property holds the message as an SPMobileSmsMessage object.

Dim smsBuilder As New SPMobileMessageSmsBuilder(account)
smsBuilder.AddRecipient(mobile_telephone_number)

' Begin the message building transaction
smsBuilder.StartTextMessage()

' Add the message text, split as needed into chunks.
Dim messageParts As List(Of StringBuilder) = SplitLongMessage(message)
For Each chunk As StringBuilder In messageParts
    smsBuilder.AddChunk(chunk.ToString())
Next

' Finish the transaction
smsBuilder.EndTextMessage()

' At this point, the smsBuilder.Message property holds the message as an SPMobileSmsMessage object

Mit der SplitLongMessage-Methode wird ein einfacher Algorithmus implementiert, um sicherzustellen, dass kein Nachrichtenabschnitt den SMS-Grenzwert von 133 (Einzelyte-) Zeichen pro verkettetem SMS-Nachrichtenabschnitt überschreitet, was manchmal auch als "lange SMS-Nachricht" bezeichnet wird. Darüber hinaus wird sichergestellt, dass Teilungen stets an einem Leerzeichen erfolgen, damit kein Wort zwischen Nachrichtenteilen geteilt wird. Ein komplexerer Algorithmus wäre erforderlich, wenn Ihre Lösung für mobiles Messaging nicht davon ausgehen kann, dass alle Zeichen der Nachricht Einzelbytezeichen sein werden.

public static List<StringBuilder> SplitLongMessage(String message)
{
    // Split the original message at white space.
    String[] words = message.Split(null);

    List<StringBuilder> chunks = new List<StringBuilder>();
    StringBuilder latestChunk = new StringBuilder(132);

    // Reconstruct the message in chunks of up to 133 characters.
    foreach (String word in words)
    {
        if (word.Length + latestChunk.Length <= 132) //Not 133 because a space will be added
        {
            latestChunk.Append(word + " "); // Add back the white space
        }
        else
        {
            // Add a copy of the chunk to the list
            chunks.Add(new StringBuilder(latestChunk.ToString()));

            // Empty out latest chunk so the next one can be started
            latestChunk.Remove(0, latestChunk.Length);

            // The word that exceeded the limit becomes the first word of the next chunk
            latestChunk.Append(word + " ");
        }
    }

    // Add the last short chunk
    if (latestChunk.Length > 0)
    {
        chunks.Add(latestChunk);
    }

    return chunks;
}

Public Shared Function SplitLongMessage(ByVal message As String) As List(Of StringBuilder)
    ' Split the original message at white space.
    Dim words() As String = message.Split(Nothing)

    Dim chunks As New List(Of StringBuilder)()
    Dim latestChunk As New StringBuilder(132)

    ' Reconstruct the message in chunks of up to 133 characters.
    For Each word As String In words
        If word.Length + latestChunk.Length <= 132 Then 'Not 133 because a space will be added
            latestChunk.Append(word & " ") ' Add back the white space
        Else
            ' Add a copy of the chunk to the list
            chunks.Add(New StringBuilder(latestChunk.ToString()))

            ' Empty out latest chunk so the next one can be started
            latestChunk.Remove(0, latestChunk.Length)

            ' The word that exceeded the limit becomes the first word of the next chunk
            latestChunk.Append(word & " ")
        End If
    Next word

    ' Add the last short chunk
    If latestChunk.Length > 0 Then
        chunks.Add(latestChunk)
    End If

    Return chunks
End Function

Unabhängig davon, ob Sie das SPMobileSmsMessage-Objekt (auf das in der SPMobileMessageBuilder.Message-Eigenschaft verwiesen wird) mit einem Aufruf von SetTextContent() oder mithilfe einer Transaktion zum Verfassen von Nachrichten erstellt haben, muss dieses Objekt vom Code in das entsprechende OMS-Format für Nachrichten-XML konvertiert werden. Hierzu wird die GetMessageXml()-Methode aufgerufen. Dieser zusätzliche Schritt zum Erstellen von XML ist nicht erforderlich, wenn Sie die Nachricht mithilfe eines Aufrufs der BuildSmsMessage(SPMobileMessagingAccount, String, String)-Methode verfassen, da sie das Nachrichten-XML zurückgibt.

String messageXml = smsBuilder.GetMessageXml();

Dim messageXml As String = smsBuilder.GetMessageXml()

Senden einer Nachricht

Eine Nachricht wird gesendet, indem das komplette, OMS-kompatible Nachrichten-XML an die SendMessage(String)-Methode eines SPMobileMessageWebService-Objekts übergeben wird. Informationen zum Erstellen eines solchen Objekts finden Sie weiter oben unter Erstellen eines Webdienstobjekts. Im folgenden Codeausschnitt ist messagingWebService ein SPMobileMessageWebService-Objekt, und messageXml ist die komplette, OMS-kompatible Nachricht.

SPMobileMessageDeliveryReport report = messagingWebService.SendMessage(messageXml);

Dim report As SPMobileMessageDeliveryReport = messagingWebService.SendMessage(messageXml)

Der von SendMessage(String) zurückgegebene Bericht enthält Informationen darüber, ob die Nachricht erfolgreich gesendet wurde, und falls dies nicht der Fall ist, die Gründe für den Fehler. Es wird empfohlen, Code zu verwenden, mit dem der Bericht verarbeitet wird, erfolgreiche Nachrichten protokolliert werden und auf Fehler reagiert wird. Informationen zur Struktur des Berichts finden Sie unter SPMobileMessageDeliveryReport.

Senden von Nachrichten im Batchmodus

Falls von Ihrer Lösung Nachrichten im Batchmodus gesendet werden, müssen die zwischen Batchaufträgen erstellten Nachrichten vom Code in einer Art Warteschlangenstruktur gespeichert werden, die nach dem Senden des Batches geleert werden kann, wie z. B. List<T><SPMobileSmsMessage>. Der Batchauftrag beginnt mit dem Erstellen eines SPMobileMessageBatchPackage-Objekts, dem jedes Nachrichtenobjekt hinzugefügt wird. Anschließend wird das Paket an die BatchSendMessages(SPMobileMessageBatchPackage)-Methode übergeben.

Im folgenden Codeausschnitt ist messageCollection ein List<T><SPMobileSmsMessage>-Objekt, und messagingWebService ist ein SPMobileMessageWebService-Objekt. Informationen zum Erstellen eines solchen Objekts finden Sie weiter oben unter Erstellen eines Webdienstobjekts.

SPMobileMessageBatchPackage package = new SPMobileMessageBatchPackage();

foreach (SPMobileSmsMessage message in messageCollection)
{
    package.AddMessage(message);
}

List<SPMobileMessageDeliveryReport> reports = messagingWebService.BatchSendMessages(package);

Dim package As New SPMobileMessageBatchPackage()

For Each message As SPMobileSmsMessage In messageCollection
    package.AddMessage(message)
Next message

Dim reports As List(Of SPMobileMessageDeliveryReport) = messagingWebService.BatchSendMessages(package)

Beachten Sie, dass es nicht erforderlich ist, die SPMobileSmsMessage-Objekte im Paket explizit in OMS-kompatible XML-Nachrichten zu konvertieren. Das Paket gibt das gesamte Batchauftrag-XML in der Xml-Eigenschaft zurück. Dieses XML wird von der BatchSendMessages(SPMobileMessageBatchPackage)-Methode an den Messagingwebdienst gesendet.

Es wird empfohlen, Code zu verwenden, mit dem die Liste der von der BatchSendMessages(SPMobileMessageBatchPackage)-Methode zurückgegebenen Berichte verarbeitet wird, erfolgreiche Nachrichten protokolliert werden und auf Fehler reagiert wird.

Weitere Webdienstmethoden

Die SPMobileMessageWebService-Klasse weist zwei weitere Methoden auf, nämlich GetUserInfo(String) und GetServiceInfo(), die als Proxys für die OMS-Webmethoden GetUserInfo bzw. GetServiceInfo dienen.

Entwickeln für andere Protokolle

Das Ableiten von einer der Klassen in Microsoft.SharePoint.MobileMessage zum Erstellen einer Lösung für mobiles Messaging, die nicht das OMS-Protokoll verwendet, wird von Microsoft nicht unterstützt. Wenn Ihre Lösung mit einem Dienstanbieter für mobiles Messaging kompatibel sein soll, der nicht das OMS-Protokoll verwendet, sollten Sie einen Webdienst erstellen, der als Verbindungsschicht zwischen APIs für mobiles Messaging von SharePoint Foundation und dem Dienstanbieter für mobiles Messaging, der ein anderes Protokoll verwendet, dient. Der Dienst würde Nachrichten von SharePoint Foundation, die das OMS-Protokoll verwenden, akzeptieren und in für den Dienstanbieter für mobiles Messaging, der das andere Protokoll verwendet, geeignete Nachrichten konvertieren.

Freigeben über