الربط بواجهة برمجة التطبيقات: تحليل مدى توافق الآراء

مستوى الترميز: متوسط
المدة: 20 دقيقة
نوع المشروع: التشغيل الآلي باستخدام قائمة مخصّصة

الأهداف

• فهم دور الحلّ
• فهم ما تفعله خدمات Apps Script ضمن الحلّ
• اضبط إعدادات البيئة.
• إعداد النص البرمجي
• شغِّل النص البرمجي.

لمحة عن هذا الحل

يمكنك تحليل البيانات النصية، مثل الملاحظات المفتوحة، على نطاق واسع. لإجراءتحليل للكيان والمشاعر من داخل "جداول بيانات Google"، يستخدم هذا الحلّ خدمة UrlFetch للاتّصال بواجهة برمجة تطبيقات Google Cloud Natural Language API.

آلية العمل

يجمع النص البرمجي النصوص من جدول البيانات ويتصل بواجهة برمجة التطبيقات Google Cloud Natural Language API لتحليل الكيانات والمشاعر المتوفّرة في السلسلة. يلخِّص الجدول المحوري متوسّط نتيجة المشاعر لكلّ كيان مُشار إليه في جميع صفوف بيانات النص.

خدمات "برمجة تطبيقات Google"

يستخدم هذا الحلّ الخدمات التالية:

• خدمة جداول البيانات: تُرسِل بيانات النص إلى Google Cloud Natural Language API وتضع علامة "مكتمل" على كل صف بعد تحليل المشاعر المرتبطة به.
• خدمة UrlFetch: تتصل بخدمة Google Cloud Natural Language API لإجراء تحليل لكيانات النص ومشاعره.

المتطلبات الأساسية

لاستخدام هذا العيّنة، يجب استيفاء المتطلبات الأساسية التالية:

• حساب Google (قد تحتاج حسابات Google Workspace إلى موافقة المشرف).

• متصفح ويب يمكنه الوصول إلى الإنترنت

• مشروع على Google Cloud مرتبط بحساب فوترة راجِع مقالة تفعيل الفوترة لمشروع.

إعداد البيئة

فتح مشروعك على Cloud في Google Cloud Console

افتح مشروع Cloud الذي تريد استخدامه لهذه العيّنة إذا لم يكن مفتوحًا من قبل:

1. في وحدة تحكّم Google Cloud، انتقِل إلى صفحة اختيار مشروع.

   اختيار مشروع على السحابة الإلكترونية

2. اختَر مشروع Google Cloud الذي تريد استخدامه. أو انقر على إنشاء مشروع واتّبِع التعليمات الظاهرة على الشاشة. في حال إنشاء مشروع على Google Cloud، قد تحتاج إلى تفعيل الفوترة للمشروع.

تفعيل Google Cloud Natural Language API

يتصل هذا الحل بواجهة برمجة التطبيقات Google Cloud Natural Language API. قبل استخدام واجهات برمجة تطبيقات Google، عليك تفعيلها في مشروع على Google Cloud. يمكنك تفعيل واجهة برمجة تطبيقات واحدة أو أكثر في مشروع واحد على Google Cloud.

• في مشروعك على Cloud، فعِّل Google Cloud Natural Language API.

  تفعيل واجهة برمجة التطبيقات

ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

يتطلب هذا الحلّ مشروعًا على Cloud يتضمّن شاشة موافقة تم ضبطها. من خلال ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth، يمكنك تحديد ما تعرضه Google للمستخدمين وتسجيل تطبيقك كي تتمكّن من نشره لاحقًا.

1. في وحدة تحكّم Google Cloud، انتقِل إلى رمز القائمة > APIs & Services (واجهات برمجة التطبيقات والخدمات) > OAuth consent screen (شاشة موافقة OAuth).

   الانتقال إلى شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

2. في حقل نوع المستخدم، اختَر داخلي، ثم انقر على إنشاء.
3. املأ نموذج تسجيل التطبيق، ثم انقر على حفظ ومتابعة.

4. في الوقت الحالي، يمكنك تخطّي إضافة النطاقات والنقر على حفظ ومتابعة. في المستقبل، عند إنشاء تطبيق لاستخدامه خارج مؤسستك على Google Workspace، عليك تغيير نوع المستخدم إلى خارجي، ثم إضافة نطاقات التفويض التي يتطلبها تطبيقك.

5. راجِع ملخّص تسجيل تطبيقك. لإجراء تغييرات، انقر على تعديل. إذا كان تسجيل التطبيق يبدو جيدًا، انقر على الرجوع إلى لوحة البيانات.

الحصول على مفتاح واجهة برمجة تطبيقات لخدمة Google Cloud Natural Language API

1. انتقِل إلى Google Cloud Console. تأكَّد من أنّ مشروعك المفعَّل فيه خيار الفوترة مفتوح.

2. في وحدة تحكّم Google Cloud، انتقِل إلى رمز القائمة > واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.

   الانتقال إلى "بيانات الاعتماد"

3. انقر على إنشاء بيانات اعتماد > مفتاح واجهة برمجة التطبيقات.

4. سجِّل مفتاح واجهة برمجة التطبيقات لاستخدامه في خطوة لاحقة.

إعداد النص البرمجي

إنشاء مشروع "برمجة تطبيقات Google"

1. انقر على الزر أدناه لإنشاء نسخة من نموذج جدول البيانات تحليل المشاعر لتحليل ملاحظات وآراء العملاء. يتم إرفاق مشروع Apps Script لهذا الحل بجدول البيانات.
   إنشاء نسخة
2. انقر على الإضافات > برمجة تطبيقات Google.
3. عدِّل المتغيّر التالي في ملف النص البرمجي باستخدام مفتاح واجهة برمجة التطبيقات:

   const myApiKey = 'YOUR_API_KEY'; // Replace with your API key.

4. انقر على رمز الحفظ .

إضافة بيانات نصية

1. ارجع إلى جدول البيانات.
2. أضِف بيانات نصية إلى عمودَي id وcomments. يمكنك استخدام نموذج مراجعات عن العقارات المخصّصة للعطلات من Kaggle أو استخدام بياناتك الخاصة. يمكنك إضافة المزيد من الأعمدة إذا لزم الأمر، ولكن لكي يتم تنفيذ الرمز البرمجي بنجاح، يجب أن يحتوي على بيانات في عمودَي id وcomments.

تشغيل النص البرمجي

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

2. امنح الإذن للنصّ البرمجي عند مطالبتك بذلك. إذا ظهرت الرسالة التحذيرية لم يتم التحقّق من هذا التطبيق على شاشة موافقة OAuth، يمكن المتابعة من خلال النقر على الإعدادات المتقدّمة > الانتقال إلى {Project Name} (غير آمن).

3. انقر على أدوات المشاعر > وضع علامة على الكيانات والمشاعر مرة أخرى.

4. عند انتهاء النص البرمجي، انتقِل إلى ورقة بيانات الجدول المحوري للاطّلاع على النتائج.

مراجعة الرمز

لمراجعة رمز Apps Script لهذا الحلّ، انقر على عرض رمز المصدر أدناه:

عرض رمز المصدر

Code.gs

solutions/automations/feedback-sentiment-analysis/code.js

العرض على GitHub

// To learn how to use this script, refer to the documentation:
// https://developers.google.com/apps-script/samples/automations/feedback-sentiment-analysis

/*
Copyright 2022 Google LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

// Sets API key for accessing Cloud Natural Language API.
const myApiKey = 'YOUR_API_KEY'; // Replace with your API key.

// Matches column names in Review Data sheet to variables.
let COLUMN_NAME = {
  COMMENTS: 'comments',
  ENTITY: 'entity_sentiment',
  ID: 'id'
};

/**
 * Creates a Demo menu in Google Spreadsheets.
 */
function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu('Sentiment Tools')
    .addItem('Mark entities and sentiment', 'markEntitySentiment')
    .addToUi();
};

/**
* Analyzes entities and sentiment for each comment in  
* Review Data sheet and copies results into the 
* Entity Sentiment Data sheet.
*/
function markEntitySentiment() {
  // Sets variables for "Review Data" sheet
  let ss = SpreadsheetApp.getActiveSpreadsheet();
  let dataSheet = ss.getSheetByName('Review Data');
  let rows = dataSheet.getDataRange();
  let numRows = rows.getNumRows();
  let values = rows.getValues();
  let headerRow = values[0];

  // Checks to see if "Entity Sentiment Data" sheet is present, and
  // if not, creates a new sheet and sets the header row.
  let entitySheet = ss.getSheetByName('Entity Sentiment Data');
  if (entitySheet == null) {
   ss.insertSheet('Entity Sentiment Data');
   let entitySheet = ss.getSheetByName('Entity Sentiment Data');
   let esHeaderRange = entitySheet.getRange(1,1,1,6);
   let esHeader = [['Review ID','Entity','Salience','Sentiment Score',
                    'Sentiment Magnitude','Number of mentions']];
   esHeaderRange.setValues(esHeader);
  };

  // Finds the column index for comments, language_detected, 
  // and comments_english columns.
  let textColumnIdx = headerRow.indexOf(COLUMN_NAME.COMMENTS);
  let entityColumnIdx = headerRow.indexOf(COLUMN_NAME.ENTITY);
  let idColumnIdx = headerRow.indexOf(COLUMN_NAME.ID);
  if (entityColumnIdx == -1) {
    Browser.msgBox("Error: Could not find the column named " + COLUMN_NAME.ENTITY + 
                   ". Please create an empty column with header \"entity_sentiment\" on the Review Data tab.");
    return; // bail
  };

  ss.toast("Analyzing entities and sentiment...");
  for (let i = 0; i < numRows; ++i) {
    let value = values[i];
    let commentEnCellVal = value[textColumnIdx];
    let entityCellVal = value[entityColumnIdx];
    let reviewId = value[idColumnIdx];

    // Calls retrieveEntitySentiment function for each row that has a comment 
    // and also an empty entity_sentiment cell value.
    if(commentEnCellVal && !entityCellVal) {
        let nlData = retrieveEntitySentiment(commentEnCellVal);
        // Pastes each entity and sentiment score into Entity Sentiment Data sheet.
        let newValues = []
        for (let entity in nlData.entities) {
          entity = nlData.entities [entity];
          let row = [reviewId, entity.name, entity.salience, entity.sentiment.score, 
                     entity.sentiment.magnitude, entity.mentions.length
                    ];
          newValues.push(row);
        }
      if(newValues.length) {
        entitySheet.getRange(entitySheet.getLastRow() + 1, 1, newValues.length, newValues[0].length).setValues(newValues);
      }
        // Pastes "complete" into entity_sentiment column to denote completion of NL API call.
        dataSheet.getRange(i+1, entityColumnIdx+1).setValue("complete");
     }
   }
};

/**
 * Calls the Cloud Natural Language API with a string of text to analyze
 * entities and sentiment present in the string.
 * @param {String} the string for entity sentiment analysis
 * @return {Object} the entities and related sentiment present in the string
 */
function retrieveEntitySentiment (line) {
  let apiKey = myApiKey;
  let apiEndpoint = 'https://language.googleapis.com/v1/documents:analyzeEntitySentiment?key=' + apiKey;
  // Creates a JSON request, with text string, language, type and encoding
  let nlData = {
    document: {
      language: 'en-us',
      type: 'PLAIN_TEXT',
      content: line
    },
    encodingType: 'UTF8'
  };
  // Packages all of the options and the data together for the API call.
  let nlOptions = {
    method : 'post',
    contentType: 'application/json',  
    payload : JSON.stringify(nlData)
  };
  // Makes the API call.
  let response = UrlFetchApp.fetch(apiEndpoint, nlOptions);
  return JSON.parse(response);
};

المساهمون

تُعدّ Google هذه العينة بمساعدة خبراء Google Developers.

الخطوات التالية

• مدوّنة: تحليل النصوص في "جداول بيانات Google" باستخدام Google Cloud Natural Language API و"برمجة تطبيقات Google"
• مستندات Google Cloud Natural Language API