OAuth را با APIهای نمایه کسب و کار پیاده کنید

هر درخواستی که برنامه شما به APIهای پروفایل تجاری ارسال می‌کند، باید شامل یک توکن مجوز باشد. توکن مجوز، کاربر یا برنامه را برای گوگل مشخص می‌کند که به آن اجازه دسترسی به APIهای پروفایل تجاری را می‌دهد. برنامه شما باید از پروتکل OAuth 2.0 برای مجوزدهی درخواست‌ها استفاده کند.

این راهنما روش‌های مختلفی را که می‌توانید برای پیاده‌سازی OAuth 2.0 در پلتفرم خود استفاده کنید، توضیح می‌دهد. پلتفرم هویت گوگل، قابلیت ورود به سیستم گوگل و OAuth را که در سراسر این راهنما استفاده می‌شود، ارائه می‌دهد.

برای درک بیشتر نحوه استفاده از Oauth 2.0 برای برنامه‌های وب سرور، لطفاً به راهنمای اینجا مراجعه کنید.

پیاده‌سازی OAuth 2.0 مزایای زیر را ارائه می‌دهد:

• از دسترسی به داده‌های صاحب کسب‌وکار محافظت می‌کند.
• هویت صاحب کسب‌وکار را هنگام ورود به حساب گوگل خود احراز می‌کند.
• مشخص می‌کند که یک پلتفرم یا برنامه شریک می‌تواند با رضایت صریح صاحب کسب‌وکار به داده‌های موقعیت مکانی دسترسی پیدا کرده و آنها را تغییر دهد. مالک می‌تواند بعداً این دسترسی را لغو کند.
• هویت پلتفرم شریک را مشخص می‌کند.
• پلتفرم‌های همکار را قادر می‌سازد تا اقدامات آنلاین یا آفلاین را از طرف صاحب کسب‌وکار انجام دهند. این شامل پاسخ به نظرات، ایجاد پست‌ها و به‌روزرسانی موارد منو می‌شود.

دسترسی به API با OAuth 2.0

قبل از شروع، باید پروژه Google Cloud خود را پیکربندی کرده و APIهای پروفایل تجاری را فعال کنید. برای اطلاعات بیشتر، به مستندات مربوط به تنظیمات اولیه مراجعه کنید.

پیکربندی OAuth و صفحه رضایت

برای ایجاد اعتبارنامه و صفحه رضایت، این مراحل را دنبال کنید:

1. از صفحه Credentials در کنسول API، روی Create credentials کلیک کنید و از لیست کشویی، گزینه "OAuth Client ID" را انتخاب کنید.
2. نوع درخواست خود را انتخاب کنید، اطلاعات مربوطه را پر کنید و روی ایجاد کلیک کنید.
3. روی ذخیره کلیک کنید.
4. تنظیمات صفحه رضایت OAuth را به‌روزرسانی کنید. از آنجا، می‌توانید نام و لوگوی برنامه را به‌روزرسانی کنید، همچنین پیوندی به شرایط خدمات و سیاست حفظ حریم خصوصی خود قرار دهید.

تصویر زیر فیلدهای نام و لوگوی برنامه را در صفحه رضایت OAuth نشان می‌دهد:

تصویر زیر فیلدهای اضافی را که در صفحه رضایت OAuth ظاهر می‌شوند، نشان می‌دهد:

تصویر زیر نمونه‌ای از چیزی است که کاربر ممکن است قبل از ارائه رضایت ببیند:

روش‌های ترکیب OAuth 2.0

برای پیاده‌سازی OAuth 2.0 می‌توانید از روش‌های زیر استفاده کنید:

• کتابخانه‌های کلاینت
• ورود به سیستم گوگل
  • دسترسی آفلاین
  • فقط دسترسی آنلاین

محتوای زیر اطلاعاتی در مورد این روش‌ها برای گنجاندن OAuth 2.0 در برنامه شما ارائه می‌دهد.

دامنه‌های مجوز

به یکی از حوزه‌های OAuth زیر نیاز دارد:

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

دامنه plus.business.manage منسوخ شده است و برای حفظ سازگاری با نسخه‌های قبلی برای پیاده‌سازی‌های موجود در دسترس است.

کتابخانه‌های کلاینت

مثال‌های مختص زبان در این صفحه از کتابخانه‌های کلاینت API گوگل برای پیاده‌سازی احراز هویت OAuth 2.0 استفاده می‌کنند. برای اجرای نمونه‌های کد، ابتدا باید کتابخانه کلاینت را برای زبان خود نصب کنید.

کتابخانه‌های کلاینت برای زبان‌های زیر در دسترس هستند:

• برو
• جاوا
• دات نت
• نود جی اس
• پی اچ پی
• پایتون
• روبی

ورود به سیستم گوگل

ورود به سیستم با گوگل سریع‌ترین راه برای ادغام OAuth در پلتفرم شماست. این سرویس برای اندروید، iOS، وب و موارد دیگر در دسترس است.

ورود به سیستم گوگل (Google Sign-In) یک سیستم احراز هویت امن است که به کاربران امکان می‌دهد با حساب گوگل خود وارد سیستم شوند، که همان حسابی است که برای ورود به سایر سرویس‌های گوگل از آن استفاده می‌کنند. پس از ورود کاربر، او می‌تواند به برنامه شما اجازه دهد تا APIهای پروفایل تجاری را فراخوانی کند و کد مجوزی را که برای دریافت توکن‌های به‌روزرسانی و دسترسی استفاده می‌شود، مبادله کند.

دسترسی آفلاین

شاید بخواهید APIهای پروفایل تجاری را از طرف یک کاربر، حتی زمانی که کاربر آفلاین است، فراخوانی کنید. توصیه می‌شود پلتفرم‌ها این قابلیت را در خود جای دهند، زیرا می‌توانید هر زمان که کاربر وارد سیستم شد و رضایت خود را اعلام کرد، فهرست‌ها را ویرایش، مشاهده و مدیریت کنید.

گوگل فرض می‌کند که کاربر قبلاً با حساب گوگل خود وارد سیستم شده است، به برنامه شما اجازه داده است تا APIهای پروفایل تجاری را فراخوانی کند و یک کد مجوز رد و بدل کرده است که سپس برای دریافت یک توکن به‌روزرسانی و بعداً یک توکن دسترسی استفاده می‌شود. کاربر می‌تواند توکن به‌روزرسانی را به صورت ایمن ذخیره کند و بعداً از آن برای دریافت یک توکن دسترسی جدید در هر زمان استفاده کند. برای اطلاعات بیشتر، بخش ورود به سیستم گوگل برای برنامه‌های سمت سرور را مطالعه کنید.

قطعه کد زیر نحوه پیاده‌سازی دسترسی آفلاین را در برنامه شما نشان می‌دهد. برای اجرای این کد، به بخش اجرای نمونه مراجعه کنید.

هشدار: این کد صرفاً جهت نمایش است. هرگز کلید API خود را در سمت کلاینت نمایش ندهید.

<!-- 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>

فقط دسترسی آنلاین

برای سهولت پیاده‌سازی، فراخوانی‌ها از APIهای پروفایل تجاری ممکن است بدون ذخیره توکن‌های به‌روزرسانی کاربر انجام شوند. با این حال، برای انجام فراخوانی‌های API توسط پلتفرم، کاربر باید به عنوان کاربر وارد سیستم شود.

قطعه کد زیر پیاده‌سازی جریان ورود به سیستم گوگل و نحوه‌ی فراخوانی API مخصوص کاربر را نشان می‌دهد. پس از اینکه کاربر با حساب گوگل خود وارد سیستم شد و به برنامه‌ی شما رضایت داد، یک توکن دسترسی اعطا می‌شود. این توکن دسترسی، کاربر را شناسایی می‌کند و لازم است به عنوان سربرگ در درخواست 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>

توجه: برای اطلاعات بیشتر در مورد ادغام، به «ورود با گوگل» مراجعه کنید.

نمونه را اجرا کنید

برای اجرای کد نمونه ارائه شده، مراحل زیر را انجام دهید:

1. قطعه کد را در فایلی با عنوان index.html ذخیره کنید. مطمئن شوید که شناسه کلاینت خود را در فایل تنظیم کرده‌اید.

2. وب سرور را با دستور زیر از دایرکتوری کاری خود شروع کنید:

   پایتون ۲.X

   python -m SimpleHTTPServer 8000

   پایتون ۳.X

   python -m http.server 8000

3. از صفحه اعتبارنامه‌ها در کنسول API، شناسه کلاینت مورد استفاده را انتخاب کنید.

4. در قسمت Authorized JavaScript origins ، آدرس وب‌سایت خود را وارد کنید. برای اجرای کد نمونه در این راهنما، باید http://localhost:8000 را نیز اضافه کنید.

5. آدرس زیر را در مرورگر خود بارگذاری کنید:

   http://localhost:8000/index.html