التعرّف على مفاهيم واجهة برمجة التطبيقات Media API

تسمح واجهة برمجة التطبيقات Google Meet Media API لتطبيقك بالانضمام إلى مؤتمر على Google Meet واستخدام بث الوسائط في الوقت الفعلي.

تستخدم البرامج WebRTC للتواصل مع خوادم Meet. تعرض البرامج المرجعية المقدَّمة (C++ وTypeScript) أفضل الممارسات، ونشجّعك على الاستفادة منها مباشرةً.

ومع ذلك، يمكنك أيضًا إنشاء برامج WebRTC مخصّصة بالكامل تتوافق مع المتطلبات الفنية لواجهة برمجة التطبيقات Meet Media API.

توضّح هذه الصفحة مفاهيم WebRTC الرئيسية المطلوبة لإجراء جلسة ناجحة باستخدام Meet Media API.

إشارات العرض والردّ

‫WebRTC هو إطار عمل من نظير إلى نظير (P2P)، حيث يتواصل النظراء من خلال إرسال إشارات إلى بعضهم البعض. لبدء جلسة، يرسل النظير الذي يبدأ الجلسة عرض SDP offer إلى نظير بعيد. يتضمّن هذا العرض التفاصيل المهمة التالية:

أوصاف الوسائط للصوت والفيديو

توضّح أوصاف الوسائط ما يتم إرساله خلال جلسات P2P. هناك ثلاثة أنواع من الأوصاف: الصوت والفيديو والبيانات.

للإشارة إلى n من بث الصوت، يدرج مقدّم العرض n من أوصاف الوسائط الصوتية في العرض. وينطبق الأمر نفسه على الفيديو. ومع ذلك، لن يكون هناك سوى وصف واحد للوسائط البيانية على الأكثر.

اتجاهات الطريق

يصف كل وصف صوتي أو فيديو بث بروتوكول النقل الآمن في الوقت الفعلي (SRTP) فردي، محكوم بـ RFC 3711. هذه البث ثنائية الاتجاه، ما يسمح لنظيرين بإرسال الوسائط وتلقّيها عبر الاتصال نفسه.

لهذا السبب، يحتوي كل وصف للوسائط (في كلّ من العرض والردّ) على إحدى السمات الثلاث التي تصف كيفية استخدام البث:

• sendonly: لا يتم إرسال الوسائط إلا من النظير الذي يقدّم العرض. لن يرسل النظير البعيد الوسائط على هذا البث.

• recvonly: لا يتم تلقّي الوسائط إلا من النظير البعيد. لن يرسل النظير الذي يقدّم العرض الوسائط على هذا البث.

• sendrecv: يمكن لكلا النظيرين إرسال الوسائط وتلقّيها على هذا البث.

برامج الترميز

يحدّد كل وصف للوسائط أيضًا برامج الترميز التي يتيحها النظير. في حالة Meet Media API، يتم رفض عروض البرامج ما لم تكن تتيح (على الأقل) برامج الترميز المحدّدة في المتطلبات الفنية.

المصافحة باستخدام بروتوكول أمان طبقة النقل لمخطّطات البيانات (DTLS)

يتم تأمين بث SRTP من خلال مصافحة أولية بين النظيرين باستخدام بروتوكول أمان طبقة النقل لمخطّطات البيانات ("DTLS", RFC 9147). عادةً ما يكون DTLS بروتوكولاً من العميل إلى الخادم، وخلال عملية الإشارة، يوافق أحد النظيرين على العمل كخادم بينما يعمل الآخر كنظير.

بما أنّ كل بث SRTP قد يكون له اتصال DTLS مخصّص، يحدّد كل وصف للوسائط إحدى السمات الثلاث للإشارة إلى دور النظير في المصافحة باستخدام DTLS:

• a=setup:actpass: يترك النظير الذي يقدّم العرض الخيار للنظير البعيد.

• a=setup:active: يعمل هذا النظير كعميل.

• a=setup:passive: يعمل هذا النظير كخادم.

أوصاف وسائط التطبيق

قنوات البيانات (RFC 8831) هي تجريد لـ بروتوكول نقل التحكّم في البث ("SCTP"، RFC 9260).

لفتح قنوات البيانات خلال مرحلة الإشارة الأولية، يجب أن يحتوي العرض على وصف لوسائط التطبيق. على عكس أوصاف الصوت والفيديو، لا تحدّد أوصاف التطبيق الاتجاه أو برامج الترميز.

مرشّحو ICE

مرشّحو بروتوكول إنشاء الاتصال التفاعلي ("ICE", RFC 8445) لنظير ما هم قائمة بالمسارات التي يمكن أن يستخدمها نظير بعيد لإنشاء اتصال.

يمثّل ناتج الضرب الديكارتي لقائمتَي النظيرين، المعروف باسم أزواج المرشّحين، المسارات المحتمَلة بين نظيرين. يتم اختبار هذه الأزواج لتحديد المسار الأمثل.

الإشارة من خلال Meet REST API

استخدِم Meet REST API لإجراء إشارات العرض والردّ هذه. يقدّم تطبيقك عرض SDP إلى طريقة connectActiveConference() ويتلقّى رد SDP في المقابل.

تعرض عيّنات التعليمات البرمجية التالية كيفية استدعاء الطريقة:

import com.google.api.core.ApiFuture;
import com.google.apps.meet.v2beta.ConnectActiveConferenceRequest;
import com.google.apps.meet.v2beta.ConnectActiveConferenceResponse;
import com.google.apps.meet.v2beta.SpaceName;
import com.google.apps.meet.v2beta.SpacesServiceClient;

public class AsyncConnectActiveConference {

  public static void main(String[] args) throws Exception {
    asyncConnectActiveConference();
  }

  public static void asyncConnectActiveConference() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (SpacesServiceClient spacesServiceClient = SpacesServiceClient.create()) {
      ConnectActiveConferenceRequest request =
          ConnectActiveConferenceRequest.newBuilder()
              .setName(SpaceName.of("[SPACE]").toString())
              .setOffer("offer105650780")
              .build();
      ApiFuture<ConnectActiveConferenceResponse> future =
          spacesServiceClient.connectActiveConferenceCallable().futureCall(request);
      // Do something.
      ConnectActiveConferenceResponse response = future.get();
    }
  }
}

using Google.Apps.Meet.V2Beta;
using System.Threading.Tasks;

public sealed partial class GeneratedSpacesServiceClientSnippets
{
    /// <summary>Snippet for ConnectActiveConferenceAsync</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public async Task ConnectActiveConferenceAsync()
    {
        // Create client
        SpacesServiceClient spacesServiceClient = await SpacesServiceClient.CreateAsync();
        // Initialize request argument(s)
        string name = "spaces/[SPACE]";
        // Make the request
        ConnectActiveConferenceResponse response = await spacesServiceClient.ConnectActiveConferenceAsync(name);
    }
}

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. Resource name of the space.
 *  Format: spaces/{spaceId}
 */
// const name = 'abc123'
/**
 *  Required. WebRTC SDP (Session Description Protocol) offer from the client.
 *  The format is defined by RFC
 *  8866 (https://www.rfc-editor.org/rfc/rfc8866) with mandatory keys defined
 *  by RFC 8829 (https://www.rfc-editor.org/rfc/rfc8829). This is the standard
 *  SDP format generated by a peer connection's createOffer() and
 *  createAnswer() methods.
 */
// const offer = 'abc123'

// Imports the Meet library
const {SpacesServiceClient} = require('@google-apps/meet').v2beta;

// Instantiates a client
const meetClient = new SpacesServiceClient();

async function callConnectActiveConference() {
  // Construct request
  const request = {
    name,
    offer,
  };

  // Run request
  const response = await meetClient.connectActiveConference(request);
  console.log(response);
}

callConnectActiveConference();

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.apps import meet_v2beta


async def sample_connect_active_conference():
    # Create a client
    client = meet_v2beta.SpacesServiceAsyncClient()

    # Initialize request argument(s)
    request = meet_v2beta.ConnectActiveConferenceRequest(
        name="name_value",
        offer="offer_value",
    )

    # Make the request
    response = await client.connect_active_conference(request=request)

    # Handle the response
    print(response)

مثال على تدفق الاتصال

في ما يلي عرض يتضمّن وصفًا لوسائط الصوت:

يردّ النظير البعيد بعرض SDP answer يحتوي على العدد نفسه من أسطر وصف الوسائط. يشير كل سطر إلى الوسائط التي يرسلها النظير البعيد إلى العميل الذي يقدّم العرض عبر بث SRTP، إن وُجدت. قد يرفض النظير البعيد أيضًا بثًا معيّنًا من مقدّم العرض من خلال ضبط إدخال وصف الوسائط هذا على recvonly.

بالنسبة إلى Meet Media API، يرسل العملاء دائمًا عرض SDP لبدء اتصال. لا يبدأ Meet الاتصال أبدًا.

تتم إدارة هذا السلوك داخليًا من قِبل البرامج المرجعية (C++‎ وTypeScript)، ولكن يمكن لمطوّري البرامج المخصّصة استخدام PeerConnectionInterface في WebRTC لـ إنشاء عرض.

للاتصال بـ Meet، يجب أن يتوافق العرض مع متطلبات معيّنة :

1. يجب أن يعمل العميل دائمًا كعميل في المصافحة باستخدام DTLS، لذا يجب أن يحدّد كل وصف للوسائط في العرض إما a=setup:actpass أو a=setup:active.

2. يجب أن يتيح كل سطر وصف للوسائط جميع برامج الترميز المطلوبة لنوع الوسائط هذا:

   • الصوت: Opus
   • الفيديو: VP8 وVP9 وAV1

3. لتلقّي الصوت، يجب أن يتضمّن العرض 3 أوصاف لوسائط الصوت التي لا يمكن إلا تلقّيها. يمكنك إجراء ذلك من خلال ضبط أجهزة الإرسال والاستقبال على عنصر اتصال النظير.

   C++‎

   // ...
   rtc::scoped_refptr<webrtc::PeerConnectionInterface> peer_connection;
   
   for (int i = 0; i < 3; ++i) {
     webrtc::RtpTransceiverInit audio_init;
     audio_init.direction = webrtc::RtpTransceiverDirection::kRecvOnly;
     audio_init.stream_ids = {absl::StrCat("audio_stream_", i)};
   
     webrtc::RTCErrorOr<rtc::scoped_refptr<webrtc::RtpTransceiverInterface>>
       audio_result = peer_connection->AddTransceiver(
         cricket::MediaType::MEDIA_TYPE_AUDIO, audio_init);
   
     if (!audio_result.ok()) {
       return absl::InternalError(absl::StrCat("Failed to add audio transceiver: ",
                                               audio_result.error().message()));
     }
   }
   

   JavaScript

   pc = new RTCPeerConnection();
   
   // Configure client to receive audio from Meet servers.
   pc.addTransceiver('audio', {'direction':'recvonly'});
   pc.addTransceiver('audio', {'direction':'recvonly'});
   pc.addTransceiver('audio', {'direction':'recvonly'});
   

4. لتلقّي الفيديو، يجب أن يتضمّن العرض وصفًا واحدًا إلى ثلاثة أوصاف لوسائط الفيديو التي لا يمكن إلا تلقّيها. يمكنك إجراء ذلك من خلال ضبط أجهزة الإرسال والاستقبال على عنصر اتصال النظير.

   C++‎

   // ...
   rtc::scoped_refptr<webrtc::PeerConnectionInterface> peer_connection;
   
   for (uint32_t i = 0; i < configurations.receiving_video_stream_count; ++i) {
     webrtc::RtpTransceiverInit video_init;
     video_init.direction = webrtc::RtpTransceiverDirection::kRecvOnly;
     video_init.stream_ids = {absl::StrCat("video_stream_", i)};
   
     webrtc::RTCErrorOr<rtc::scoped_refptr<webrtc::RtpTransceiverInterface>>
         video_result = peer_connection->AddTransceiver(
           cricket::MediaType::MEDIA_TYPE_VIDEO, video_init);
   
     if (!video_result.ok()) {
       return absl::InternalError(absl::StrCat("Failed to add video transceiver: ",
                                               video_result.error().message()));
     }
   }
   

   JavaScript

   pc = new RTCPeerConnection();
   
   // Configure client to receive video from Meet servers.
   pc.addTransceiver('video', {'direction':'recvonly'});
   pc.addTransceiver('video', {'direction':'recvonly'});
   pc.addTransceiver('video', {'direction':'recvonly'});
   

5. يجب أن يتضمّن العرض دائمًا قنوات البيانات. في الحد الأدنى، يجب أن تكون قناتا session-control وmedia-stats مفتوحتَين دائمًا. يجب أن تكون جميع قنوات البيانات ordered.

   C++‎

   // ...
   // All data channels must be ordered.
   constexpr webrtc::DataChannelInit kDataChannelConfig = {.ordered = true};
   
   rtc::scoped_refptr<webrtc::PeerConnectionInterface> peer_connection;
   
   // Signal session-control data channel.
   webrtc::RTCErrorOr<rtc::scoped_refptr<webrtc::DataChannelInterface>>
     session_create_result = peer_connection->CreateDataChannelOrError(
       "session-control", &kDataChannelConfig);
   
   if (!session_create_result.ok()) {
     return absl::InternalError(absl::StrCat("Failed to create data channel ",
                                             data_channel_label, ": ",
                                             session_create_result.error().message()));
   }
   
   // Signal media-stats data channel.
   webrtc::RTCErrorOr<rtc::scoped_refptr<webrtc::DataChannelInterface>>
     stats_create_result = peer_connection->CreateDataChannelOrError(
       "media-stats", &kDataChannelConfig);
   
   if (!stats_create_result.ok()) {
     return absl::InternalError(absl::StrCat("Failed to create data channel ",
                                             data_channel_label, ": ",
                                             stats_create_result.error().message()));
   }
   

   JavaScript

   // ...
   pc = new RTCPeerConnection();
   
   // All data channels must be ordered.
   const dataChannelConfig = {
     ordered: true,
   };
   
   // Signal session-control data channel.
   sessionControlChannel = pc.createDataChannel('session-control', dataChannelConfig);
   sessionControlChannel.onopen = () => console.log("data channel is now open");
   sessionControlChannel.onclose = () => console.log("data channel is now closed");
   sessionControlChannel.onmessage = async (e) => {
     console.log("data channel message", e.data);
   };
   
   // Signal media-stats data channel.
   mediaStatsChannel = pc.createDataChannel('media-stats', dataChannelConfig);
   mediaStatsChannel.onopen = () => console.log("data channel is now open");
   mediaStatsChannel.onclose = () => console.log("data channel is now closed");
   mediaStatsChannel.onmessage = async (e) => {
     console.log("data channel message", e.data);
   };
   

مثال على عرض SDP والردّ

في ما يلي مثال كامل على عرض SDP صالح وردّ SDP مطابق. يتفاوض هذا العرض على جلسة Meet Media API تتضمّن الصوت وبث فيديو واحدًا.

لاحظ أنّ هناك ثلاثة أوصاف لوسائط الصوت ووصفًا واحدًا لوسائط الفيديو ووصف وسائط التطبيق المطلوب.

مواضيع ذات صلة

• البدء