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

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

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

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

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

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

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

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

ضبط بروتوكول 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
• روبي

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

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

"تسجيل الدخول بحساب 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 ويمنح الموافقة على تطبيقك، فإن رمز الدخول هو ممنوح. يحدد رمز الدخول هذا المستخدم ويجب تمريره باعتباره في طلب واجهات برمجة تطبيقات الملف التجاري.

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

<!-- 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. من Credentials (بيانات الاعتماد) في وحدة تحكم واجهة برمجة التطبيقات، اختر معرِّف العميل المُستخدَم.

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

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

   http://localhost:8000/index.html