تنفيذ بروتوكول OAuth مع واجهات Business Profile

عندما يرسل تطبيقك طلبًا إلى واجهات Business Profile API، يجب أن يتضمّن هذا الرمز رمزًا مميزًا للتفويض. يحدّد رمز التفويض المميّز المستخدم أو التطبيق في Google، ما يتيح الوصول إلى واجهات برمجة تطبيقات "الملف التجاري على Google". يجب أن يستخدم تطبيقك بروتوكول OAuth 2.0 للسماح بالطلبات.

يشرح هذا الدليل الطرق المختلفة التي يمكنك استخدامها لتنفيذ بروتوكول OAuth 2.0 على نظامك الأساسي. توفِّر منصة هوية Google وظيفتَي "تسجيل الدخول بحساب Google" وOAuth المُستخدَمة في هذا الدليل.

ولفهم كيفية استخدام Oauth 2.0 لتطبيقات خادم الويب، يُرجى الرجوع إلى الدليل هنا.

ويوفّر تنفيذ بروتوكول OAuth 2.0 المزايا التالية:

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

الوصول إلى واجهة برمجة التطبيقات باستخدام OAuth 2.0

قبل البدء، عليك ضبط مشروعك على Google Cloud وتفعيل واجهات برمجة تطبيقات "الملف التجاري على Google". لمزيد من المعلومات، راجِع وثائق الإعداد الأساسي.

إعداد OAuth وشاشة الموافقة

اتّبِع الخطوات التالية لإنشاء بيانات الاعتماد وشاشة الموافقة:

1. من صفحة بيانات الاعتماد في وحدة تحكُّم واجهة برمجة التطبيقات، انقر على إنشاء بيانات اعتماد واختَر "معرِّف عميل OAuth" من القائمة المنسدلة.
2. اختَر نوع طلبك واملأ المعلومات ذات الصلة ثمّ انقر على إنشاء.
3. انقر على حفظ.
4. عدِّل إعدادات شاشة موافقة OAuth. ومن هناك، يمكنك تحديث اسم التطبيق وشعاره، وكذلك تضمين رابط إلى بنود الخدمة وسياسة الخصوصية.

تعرِض الصورة التالية حقلَي اسم التطبيق والشعار في شاشة موافقة OAuth:

توضّح الصورة التالية حقولاً إضافية تظهر في شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth:

الصورة التالية هي مثال لما قد يظهر للمستخدم قبل تقديم موافقته:

طرق دمج OAuth 2.0

يمكنك استخدام الطرق التالية لتنفيذ OAuth 2.0:

• مكتبات العملاء
• تسجيل الدخول باستخدام حساب Google
  • الوصول إلى المحتوى بلا إنترنت
  • الوصول على الإنترنت فقط

يقدِّم المحتوى التالي معلومات عن هذه الطرق لدمج OAuth 2.0 في تطبيقك.

نطاقات الأذونات

يتطلب استخدام أحد نطاقات OAuth التالية:

• https://www.googleapis.com/auth/business.manage
• https://www.googleapis.com/auth/plus.business.manage

تم إيقاف نطاق plus.business.manage نهائيًا وهو متاح للحفاظ على التوافق مع الأنظمة القديمة لعمليات التنفيذ الحالية.

مكتبات العملاء

تستخدم الأمثلة الخاصة باللغات في هذه الصفحة مكتبات عميل Google API لتنفيذ تفويض OAuth 2.0. لتشغيل نماذج التعليمات البرمجية، يجب أولاً تثبيت مكتبة البرامج بلغتك.

تتوفر مكتبات العملاء باللغات التالية:

• انتقال
• Java
• .NET
• Node.js
• PHP
• Python
• Ruby

تسجيل الدخول بحساب Google

تسجيل الدخول بحساب Google هو الطريقة الأسرع لدمج OAuth في منصتك. إنها متاحة لأجهزة Android وiOS والويب وغيرها.

تسجيل الدخول بحساب Google هو نظام مصادقة آمن يتيح للمستخدمين تسجيل الدخول باستخدام حساباتهم على Google، وهو الحساب نفسه الذي يستخدمونه لتسجيل الدخول إلى خدمات Google الأخرى. بعد تسجيل المستخدم الدخول، يمكنه منح الموافقة لتطبيقك لاستدعاء واجهات برمجة تطبيقات "الملف التجاري على Google" وتبادل رمز التفويض المستخدَم للحصول على رموز إعادة التحميل والوصول.

الوصول إلى المحتوى بلا إنترنت

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

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

يعرض مقتطف الرمز التالي كيفية تنفيذ الوصول بلا اتصال بالإنترنت في تطبيقك. لتشغيل هذا الرمز، يُرجى الاطّلاع على تشغيل النموذج.

تحذير: هذا الرمز مخصّص لأغراض العرض التوضيحي. ويجب عدم الكشف عن مفتاح واجهة برمجة التطبيقات من جهة العميل مطلقًا.

<!-- The top of file index.html -->
<html itemscope itemtype="http://schema.org/Article">
<head>
  <!-- BEGIN Pre-requisites -->
  <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.8.2/jquery.min.js">
  </script>
  <script src="https://apis.google.com/js/client:platform.js?onload=start" async defer>
  </script>
  <!-- END Pre-requisites -->
<!-- Continuing the <head> section -->
  <script>
    function start() {
      gapi.load('auth2', function() {
        auth2 = gapi.auth2.init({
          client_id: 'YOUR_CLIENT_ID.apps.googleusercontent.com',
          // Scopes to request in addition to 'profile' and 'email'
          scope: 'https://www.googleapis.com/auth/business.manage',
          immediate: true
        });
      });
    }
  </script>
</head>
<body>
  <!-- Add where you want your sign-in button to render -->
<!-- Use an image that follows the branding guidelines in a real app, more info here:
 https://developers.google.com/identity/branding-guidelines
-->
<h1>Business Profile Offline Access Demo</h1>

<p> This demo demonstrates the use of Google Identity Services and OAuth to gain authorization to call the Business Profile APIs on behalf of the user, even when the user is offline.

When a refresh token is acquired, store this token securely on your database. You will then be able to use this token to refresh the OAuth credentials and make offline API calls on behalf of the user. 

The user may revoke access at any time from the <a href='https://myaccount.google.com/permissions'>Account Settings</a> page.
</p>

<button id="signinButton">Sign in with Google</button><br>
<input id="authorizationCode" type="text" placeholder="Authorization Code" style="width: 60%"><button id="accessTokenButton" disabled>Retrieve Access/Refresh Token</button><br>
 <input id="refreshToken" type="text" placeholder="Refresh Token, never expires unless revoked" style="width: 60%"><button id="refreshSubmit">Refresh Access Token</button><br>
 <input id="accessToken" type="text" placeholder="Access Token" style="width: 60%"><button id="gmbAccounts">Get Business Profile Accounts</button><br>
 <p>API Responses:</p>
<script>
    //Will be populated after sign in.
    var authCode;
  $('#signinButton').click(function() {
    // signInCallback
    auth2.grantOfflineAccess().then(signInCallback);
  });

  $('#accessTokenButton').click(function() {
    // signInCallback defined in step 6.
    retrieveAccessTokenAndRefreshToken(authCode);
  });

  $('#refreshSubmit').click(function() {
    // signInCallback defined in step 6.
    retrieveAccessTokenFromRefreshToken($('#refreshToken').val());
  });

   $('#gmbAccounts').click(function() {
    // signInCallback defined in step 6.
    retrieveGoogleMyBusinessAccounts($('#accessToken').val());
  });




function signInCallback(authResult) {
    //the 'code' field from the response, used to retrieve access token and bearer token
  if (authResult['code']) {
    // Hide the sign-in button now that the user is authorized, for example:
    $('#signinButton').attr('style', 'display: none');
    authCode = authResult['code'];

    $("#accessTokenButton").attr( "disabled", false );

    //Pretty print response
    var e = document.createElement("pre")
    e.innerHTML = JSON.stringify(authResult, undefined, 2);
    document.body.appendChild(e);

    //autofill authorization code input
    $('#authorizationCode').val(authResult['code'])

    
  } else {
    // There was an error.
  }
}

//WARNING: THIS FUNCTION IS DISPLAYED FOR DEMONSTRATION PURPOSES ONLY. YOUR CLIENT_SECRET SHOULD NEVER BE EXPOSED ON THE CLIENT SIDE!!!!
function retrieveAccessTokenAndRefreshToken(code) {
      $.post('https://www.googleapis.com/oauth2/v4/token',
      { //the headers passed in the request
        'code' : code,
        'client_id' : 'YOUR_CLIENT_ID.apps.googleusercontent.com',
        'client_secret' : 'YOUR_CLIENT_SECRET',
        'redirect_uri' : 'http://localhost:8000',
        'grant_type' : 'authorization_code'
      },
      function(returnedData) {
        console.log(returnedData);
        //pretty print JSON response
        var e = document.createElement("pre")
        e.innerHTML = JSON.stringify(returnedData, undefined, 2);
        document.body.appendChild(e);
        $('#refreshToken').val(returnedData['refresh_token'])
      });
}

//WARNING: THIS FUNCTION IS DISPLAYED FOR DEMONSTRATION PURPOSES ONLY. YOUR CLIENT_SECRET SHOULD NEVER BE EXPOSED ON THE CLIENT SIDE!!!!
function retrieveAccessTokenFromRefreshToken(refreshToken) {
    $.post('https://www.googleapis.com/oauth2/v4/token', 
        { // the headers passed in the request
        'refresh_token' : refreshToken,
        'client_id' : 'YOUR_CLIENT_ID.apps.googleusercontent.com',
        'client_secret' : 'YOUR_CLIENT_SECRET',
        'redirect_uri' : 'http://localhost:8000',
        'grant_type' : 'refresh_token'
      },
      function(returnedData) {
        var e = document.createElement("pre")
        e.innerHTML = JSON.stringify(returnedData, undefined, 2);
        document.body.appendChild(e);
        $('#accessToken').val(returnedData['access_token'])
      });
}

function retrieveGoogleMyBusinessAccounts(accessToken) {
    $.ajax({
        type: 'GET',
        url: 'https://mybusinessaccountmanagement.googleapis.com/v1/accounts',
        headers: {
            'Authorization' : 'Bearer ' + accessToken
        },
        success: function(returnedData) {
            var e = document.createElement("pre")
            e.innerHTML = JSON.stringify(returnedData, undefined, 2);
            document.body.appendChild(e);
        }
    });
}
</script>
</body>
</html>

الوصول على الإنترنت فقط

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

يوضِّح مقتطف الرمز التالي عملية تنفيذ عملية تسجيل الدخول بحساب Google وكيفية إجراء طلب بيانات من واجهة برمجة التطبيقات الخاصة بالمستخدم. بعد أن يسجّل المستخدم الدخول باستخدام حسابه في Google ويمنح موافقته على طلبك، يتم منح رمز الدخول. يحدِّد رمز الدخول هذا المستخدم ويجب تمريره كرأس في طلب Business Profile API.

لتشغيل هذا الرمز، يُرجى الاطّلاع على تشغيل النموذج.

<!-- The top of file index.html -->
<html lang="en">
  <head>
    <meta name="google-signin-scope" content="profile email https://www.googleapis.com/auth/business.manage">
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID.apps.googleusercontent.com">
    <script src="https://apis.google.com/js/platform.js" async defer></script>
  </head>
  <body>
    <div class="g-signin2" data-onsuccess="onSignIn" data-theme="dark"></div>
    <script>
      var gmb_api_version = 'https://mybusinessaccountmanagement.googleapis.com/v1';
      function onSignIn(googleUser) {
        // Useful data for your client-side scripts:
        var profile = googleUser.getBasicProfile();
        console.log('Full Name: ' + profile.getName());
        console.log("Email: " + profile.getEmail());
        var access_token = googleUser.getAuthResponse().access_token;

        //Using the sign in data to make a Business Profile APIs call
        var req = gmb_api_version + '/accounts';
        var xhr = new XMLHttpRequest();
        xhr.open('GET', req);
        xhr.setRequestHeader('Authorization', 'Bearer ' + access_token);

        //Displaying the API response
        xhr.onload = function () {
          document.body.appendChild(document.createTextNode(xhr.responseText));
        }
        xhr.send();
      }
    </script>
  </body>
</html>

ملاحظة: لمزيد من المعلومات عن عملية الدمج، يمكنك الاطّلاع على تسجيل الدخول باستخدام حساب Google.

تشغيل العيّنة

نفِّذ الخطوات التالية لتشغيل نموذج الرمز المقدم:

1. احفظ مقتطف الرمز في ملف بعنوان index.html. تأكَّد من ضبط معرّف العميل في الملف.

2. ابدأ تشغيل خادم الويب باستخدام الأمر التالي من دليل العمل:

   Python 2.X

   python -m SimpleHTTPServer 8000

   Python 3.X

   python -m http.server 8000

3. من صفحة بيانات الاعتماد في وحدة تحكّم واجهة برمجة التطبيقات، اختَر معرِّف العميل المُستخدَم.

4. ضمن الحقل مصادر JavaScript المسموح بها، أدخِل عنوان URL لموقعك الإلكتروني. لتشغيل نموذج الرمز في هذا الدليل، يجب أيضًا إضافة http://localhost:8000.

5. حمِّل عنوان URL التالي في المتصفّح:

   http://localhost:8000/index.html