Arbeiten mit der API für Anrufe und Onlinebesprechungen in Microsoft GraphWorking with the calls and online meetings API in Microsoft Graph

Wichtig

APIs unter der /beta Version in Microsoft Graph können Änderungen unterworfen werden.APIs under the /beta version in Microsoft Graph are subject to change. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt.Use of these APIs in production applications is not supported.

Durch die API für Anrufe und Onlinebesprechungen von Microsoft Graph werden die Interaktionsmöglichkeiten Ihrer Apps und Dienste mit Benutzern um Sprach- und Videofeatures erweitert.The Microsoft Graph calls and online meetings API adds a new dimension to how your apps and services can interact with users by enabling voice and video features. Mit der API können Sie Anrufe erstellen und Anrufe von Benutzern und Anwendungen in Microsoft Teams erhalten.The API enables you to create calls and receive calls from users and applications in Microsoft Teams. Mit diesen APIs können Sie eine Dienstanwendung (Bot) erstellen, die als Teilnehmer an einem Anruf oder einer Besprechung agieren kann.You can use these APIs to build a service application (bot) that can act as a participant in a call or meeting.

AnruftypenCall types

Anrufe werden als Peer-to-Peer-Anrufe oder Anrufe mit mehreren Teilnehmern kategorisiert.Calls are categorized as peer-to-peer or multiparty calls. Ein Benutzer kann einen Peer-to-Peer-Anruf mit Ihrem Bot starten oder den Bot zu einer bestehenden Konferenz mit mehreren Teilnehmern einladen.A user can initiate a peer-to-peer call with your bot or invite your bot into an existing multiparty conference. Es sind keine Berechtigungen erforderlich, wenn der Benutzer den Bot zu einem Peer-to-Peer-Aufruf einlädt.No permissions are necessary when the user is inviting the bot to a peer-to-peer call. Damit Ihr Bot an einem Gespräch mit mehreren Teilnehmern teilnehmen kann, muss er vom Mandantenadministrator die Berechtigung zur Teilnahme an einem Gruppenanruf erhalten.For your bot to participate in a multiparty call, the bot needs to have permission from the tenant administrator to join a group call.

Abbildung mit Peer-to-Peer-Anruf und Anruf mit mehreren Teilnehmern

Wenn der Bot den Anruf erstellt, muss er entweder die Berechtigung zum Initiieren eines Anrufs oder zum Initiieren eines Gruppenanrufs haben.If your bot is creating the call, it needs to have either the initiate or the initiate-group-call permission. Ihr Bot hat die Möglichkeit, Peer-to-Peer-Anrufe oder Anrufe mit mehreren Teilnehmern zu erstellen.Your bot has the option to create a peer-to-peer call or a multiparty call.

  • Für einen Peer-to-Peer-Anruf muss der Bot nur ein Ziel und keine Besprechungskoordinaten angeben.For a peer-to-peer call, the bot needs to specify only one target and no meeting coordinates.
  • Wenn Ihr Bot einen Anruf mit mehreren Teilnehmern initiiert, wird hinter den Kulissen eine Ad-hoc-Besprechung eingerichtet, der alle Personen beitreten.If your bot initiates a call with multiple participants, an ad hoc meeting is set up behind the scenes and everyone joins that conference. Falls Besprechungskoordinaten angegeben werden, wird ein Anruf mit mehreren Teilnehmern eingerichtet, auch wenn nur ein Ziel vorhanden ist.If meeting coordinates are specified, a multiparty call is set up even if there is only one target.

Ein Anruf kann als Peer-to-Peer-Anruf beginnen und zu einem Anruf mit mehreren Teilnehmern eskaliert werden.A call might start as peer-to-peer and escalate to multiparty. Es wird automatisch eine Konferenz bereitgestellt, und das Medium wird auf die Konferenz als neues Ziel umgeleitet.A conference is provisioned automatically and the media is retargeted to the conference. Ihr Bot kann die Eskalation initiieren, indem er andere Teilnehmer einlädt, sofern der Bot die Berechtigung zum Initiieren von Gruppenanrufen besitzt.Your bot can initiate escalation by inviting others, provided your bot has the initiate-group-call permission. Wenn die Eskalation von einem anderen Teilnehmer eingeleitet wird und der Bot keine Berechtigung zum Teilnehmen an Gruppenanrufen besitzt, wird der Bot aus dem Anruf entfernt.If escalation is initiated by another participant and the bot does not have join-group-call permission, your bot is dropped from the call.

Wichtig: Wenn ein Anruf von einem Peer-to-Peer-Anruf zu einem Anruf mit mehreren Teilnehmern eskaliert wird, sind nicht alle Features für mehrere Teilnehmer verfügbar.Important: When a call is escalated from peer-to-peer to multiparty, not all multiparty features are available. Insbesondere empfängt der Bot keine Listenupdates.Specifically, the bot will not receive roster updates.

SignalisierungSignaling

Eingehender AnrufIncoming call

Um einen eingehenden Anruf empfangen zu können, müssen Sie den anrufenden Bot registrieren.To receive an incoming call, you need to register the calling bot. Wenn der Bot die eingehende Benachrichtigung erhält, hat er die folgenden Optionen.When the bot receives the incoming notification, it has the following options.

MethodeMethod BeschreibungDescription
AntwortenAnswer Annehmen des eingehenden Anrufs.Answer the incoming call.
AblehnenReject Ablehnen des Anrufs und Auflegen.Reject and hangup the call.
UmleitenRedirect Umleitung des Anrufs.Redirect the call.

Der Bot kann den Aufruf zu einem anderen Benutzer oder einem Bot umleiten.The bot can redirect the call to another user or a bot. Der Bot kann ihn auch an die Voicemail eines Benutzers umleiten.The bot can also redirect it to a user's voicemail.

Abbildung mit einem Bot, der einen Anruf an eine Voicemail umleitet

Wichtig: Das Umleiten oder Tätigen ausgehender Anrufe an PSTN wird derzeit nicht unterstützt.Important: Redirecting or making outbound calls to PSTN is currently not supported.

Während des AnrufsIn-call

Vorgänge für den Bot sind im Anrufobjekt verfügbar.Operations for the bot are available on the call object. Diese wirken sich auf den Bot als Teilnehmer am Anruf aus.These affect the bot as the participant in the call.

MethodeMethod BeschreibungDescription
MuteMute Sich selbst im Anruf stummschalten.Mute self in the call.
UnmuteUnmute Stummschaltung für sich selbst in dem Anruf aufheben.Unmute self in the call.
UpdateMetadataUpdateMetadata Aktualisieren der Metadaten für sich selbst in der Teilnehmerliste.Update metadata for self in roster.
ChangeScreenSharingRoleChangeScreenSharingRole Starten und Beenden der Bildschirmübertragung in dem Anruf.Start and stop sharing screen in the call.

Verwenden Sie für die Interaktion mit anderen Teilnehmern an dem Anruf das participants-Objekt.To interact with other participants on the call, use the participants object.

MethodeMethod BeschreibungDescription
Teilnehmer auflistenList participants Abrufen einer Sammlung von Teilnehmerobjekten.Get a participant object collection.
Teilnehmer einladenInvite Participants Einladen von Teilnehmern zum aktiven Anruf.Invite participants to the active call.
Alle Teilnehmer stummschaltenMute All Participants Stummschalten aller Teilnehmer in dem Anruf.Mute all participants in the call.

MedienMedia

Die Verarbeitung von Medien wird über die Microsoft Real-Time Media-Plattform verwaltet.Media processing is managed through the Microsoft Real-time Media Platform. Über die Real-Time Media-Plattform können Bots in Microsoft Teams an Audio-/Videoanrufen und Besprechungen teilnehmen.The Real-time Media Platform helps bots engage in Microsoft Teams audio/video calls and meetings. Dadurch können Echtzeitbots an Peer-to-Peer-Anrufen und an Anrufen mit mehreren Teilnehmern teilnehmen.It allows real-time bots to participate in both peer-to-peer and multiparty calls.

Wenn der Bot auf einen eingehenden Anruf antwortet oder einem neuen oder bestehenden Anruf beitritt, muss er der Real-Time Media-Plattform mitteilen, wie Medien behandelt werden.When the bot answers an incoming call, or joins a new or existing call, it needs to tell the Real-time Media Platform how media will be handled. Wenn Sie ein IVR-System (Interactive Voice Response) erstellen, können Sie die kostspielige Audioverarbeitung auf von Microsoft gehostete Mediakomponenten verlagern.If you are building an Interactive Voice Response (IVR) system, you can offload the expensive audio processing to Microsoft service hosted media components. Für den Fall, dass Ihr Bot direkten Zugriff auf Mediendatenströme benötigt, bieten wir eine von der Anwendung gehostete Medienoption über das Real-Time Media-SDK an.If your bot requires direct access to media streams, we offer an application-hosted media option through the Real-time Media SDK.

Vom Dienst gehostete MedienService-hosted media

Bots können den Workflow verwalten und die Audioverarbeitung auf die Microsoft Real-Time Media-Plattform verlagern.Bots can manage the workflow and offload audio processing to the Microsoft Real-time Media Platform. Mit vom Dienst gehosteten Medien haben Sie mehrere Optionen zum Implementieren und Hosten Ihres Bots.With service-hosted media, you have serveral options to implement and host your bot. Erwägen Sie die Verwendung des verfügbaren SDKs.Consider using one of the available SDKs. Ein vom Dienst gehosteter Medienbot kann als statusfreier Dienst implementiert werden, da er keine Medien lokal verarbeitet.A service-hosted media bot can be implemented as a stateless service as it does not process media locally.

MethodeMethod BeschreibungDescription
PlayPromptPlayPrompt Wiedergegeben eines Audioclips für den Benutzer.Play an audio clip to the user.
RecordRecord Optionales Wiedergeben einer Eingabeaufforderung und Aufzeichnen eines Audioclips.Optionally play a prompt and record an audio clip.
SubscribeToToneSubscribeToTone Abonnieren von MFV-Tönen vom Benutzer.Subscribe to DTMF tones from the user.
CancelMediaProcessingCancelMediaProcessing Abbrechen jeglicher Medienverarbeitung, die sich bereits in der Warteschlange befindet.Cancel any media processing already queued.

Von der Anwendung gehostete MedienApplication-hosted media

Für den direkten Zugriff auf die Medien benötigt der Bot die „Access-Media“-Berechtigung.For the bot to get direct access to the media, the bot needs the Access-Media permission. Mit der Real-Time Media-Bibliothek und dem zustandsbehafteten SDK können Sie funktionsreiche Bots für Medienanrufe in Echtzeit erstellen.The Real-time Media library and the stateful SDK helps you build rich real-time media calling bots. Ein in der Anwendung gehosteter Bot muss in einer Windows-Umgebung gehostet werden.An application-hosted bot must be hosted in a Windows environment. Die Beispiele für in der Anwendung gehostete Medien veranschaulichen, wie Sie den Bot auf verschiedenen Azure-Plattformen (einschließlich Cloud Services und Service Fabric) erstellen.Application hosted media samples show how to build the bot in various Azure Platforms (including Cloud Services and Service Fabric).

Sie können das SDK für Microsoft Graph-Anrufe verwenden, um die Erstellung von Bots zu vereinfachen.You can use the Microsoft Graph Calls SDK to simplify the creation of bots. Das SDK bietet Funktionen zum Verwalten der Zustände der Ressourcen im Arbeitsspeicher und zum Abrufen des Medienstapels der Bot-Entwickler.The SDK provides functionality to manage the states of the resources in memory and to pull in bot developers' media stack.

Das Medien-SDK ermöglicht dem Bot das Senden und Empfangen von Audio, Video und Inhalten videobasierter Bildschirmübertragung.The Media SDK allows the bot to send and receive audio, video, and video-based screen sharing content. Die videobasierte Bildschirmübertragung wird als Videokanal modelliert.Video-based screen sharing is modeled as a video channel. Der Bot kann den gemischten Audiokanal und mehrere Videokanäle abonnieren.The bot can subscribe to the mixed audio channel and multiple video channels. Der Bot kann Video für den Videokanal entweder als codierten H.264-Stream oder als decodierte Raw-Frames senden und empfangen.For the video channel, the bot has a choice to send and receive video as an encoded H.264 stream or as decoded raw frames.

Hinweis: Sie dürfen die Microsoft.Graph.Calls.Media-API nicht verwenden, um Medieninhalte aus Anrufen oder Besprechungen, auf die der Bot zugreift, aufzuzeichnen oder auf andere Weise zu speichern.Note: You may not use the Microsoft.Graph.Calls.Media API to record or otherwise persist media content from calls or meetings that your bot accesses.

Siehe auchSee also

Beispiele für die API für Anrufe und OnlinebesprechungenCalls and online meetings API samples

Bekannte ProblemeKnown issues