تنفيذ الوظائف باستخدام واجهة برمجة التطبيقات لبرمجة التطبيقات

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

المتطلّبات

يجب استيفاء المتطلبات التالية قبل أن يتمكن تطبيق الاتصال من استخدام الطريقة scripts.run. عليك:

  • انشر مشروع النص البرمجي كملف تنفيذي لواجهة برمجة التطبيقات. يمكنك نشر المشاريع وإلغاء نشرها وإعادة نشرها حسب الحاجة.

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

  • تأكّد من أن النص البرمجي وعميل OAuth2 للتطبيق يشاركان مشروع Google Cloud مشتركًا. يجب أن يكون مشروع Google Cloud مشروعًا عاديًا في Google Cloud، ولا يكفي المشاريع التلقائية التي يتم إنشاؤها لمشاريع برمجة التطبيقات. يمكنك استخدام مشروع عادي جديد على السحابة الإلكترونية أو مشروع حالي حالي.

  • فعِّل Google Apps Script API في المشروع على Google Cloud.

طريقة scripts.run

تتطلّب طريقة scripts.run تحديد معلومات رئيسية للتشغيل:

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

التعامل مع أنواع بيانات المعلَمات

عادةً ما يتضمن استخدام واجهة برمجة التطبيقات لبرمجة التطبيقات scripts.run إرسال البيانات إلى برمجة التطبيقات كمعلّمات وظائف والحصول على البيانات مرة أخرى كقيم لعرض الدوال. ولا يمكن أن تأخذ واجهة برمجة التطبيقات القيم وتعرضها إلا بالأنواع الأساسية فقط: السلاسل والمصفوفات والعناصر والعناصر والأرقام المنطقية. وهي تشبه الأنواع الأساسية في JavaScript. لا يمكن تمرير كائنات برمجة التطبيقات الأكثر تعقيدًا مثل المستند أو الورقة إلى واجهة برمجة التطبيقات أو من مشروع النص البرمجي.

عندما تتم كتابة تطبيق الاستدعاء بلغة من النوع القوي، مثل Java، يتم تمريره في معلّمات كقائمة أو مصفوفة من العناصر العامة المقابلة لهذه الأنواع الأساسية. في كثير من الحالات، يمكنك تطبيق الإحالات الناجحة البسيطة من النوع تلقائيًا. على سبيل المثال، يمكن منح الدالة التي تستخدِم معلّمة رقم كائن Java Double أو Integer أو Long كمعلّمة بدون معالجة إضافية.

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

  • تظهر الأرقام التي تعرضها واجهة برمجة التطبيقات إلى تطبيق JavaScript على أنها عناصر java.math.BigDecimal، وقد تحتاج إلى تحويلها إلى أنواع Doubles أو int حسب الحاجة.
  • إذا كانت دالة "برمجة تطبيقات Google" تعرض مجموعة من السلاسل، يُرسِل تطبيق Java الاستجابة في عنصر List<String>:

    List<String> mylist = (List<String>)(op.getResponse().get("result"));
    
  • إذا كنت تريد عرض مصفوفة من Bytes، قد يكون من الأسهل ترميز المصفوفة كسلسلة base64 ضمن دالة برمجة التطبيقات وعرض هذه السلسلة بدلاً من ذلك:

    return Utilities.base64Encode(myByteArray); // returns a String.
    

توضّح أمثلة نماذج الرموز أدناه طرق تفسير استجابة استجابة واجهة برمجة التطبيقات.

الإجراء العام

يصف ما يلي الإجراء العام لاستخدام واجهة برمجة التطبيقات لبرمجة التطبيقات لتنفيذ وظائف "برمجة تطبيقات Google":

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

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

الخطوة 2: نشر النص البرمجي كملف تنفيذي لواجهة برمجة التطبيقات

  1. افتح مشروع "برمجة تطبيقات Google" باستخدام الدوال التي تريد استخدامها.
  2. في أعلى يسار الصفحة، انقر على نشر > نشر جديد.
  3. في مربّع الحوار الذي يظهر، انقر على رمز تفعيل أنواع النشر > واجهة برمجة تطبيقات قابلة للتنفيذ.
  4. في القائمة المنسدلة "من لديه حق الوصول"، اختَر المستخدمين المسموح لهم باستدعاء وظائف النص البرمجي باستخدام Apps Script API.
  5. انقر على نشر.

الخطوة 3: ضبط تطبيق الاتصال

يجب أن يُفعِّل تطبيق الاستدعاء واجهة برمجة التطبيقات لبرمجة التطبيقات وأن يثبِّت إعدادات OAuth قبل أن يتم استخدامه. عليك الوصول إلى مشروع Google Cloud لتنفيذ ذلك.

  1. اضبط المشروع على السحابة الإلكترونية الذي يستخدمه تطبيق الاتصال والنص البرمجي. ويمكنك إجراء ذلك باتّباع الخطوات التالية:
    1. فعِّل Apps Script API في المشروع على السحابة الإلكترونية.
    2. ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth
    3. إنشاء بيانات اعتماد OAuth.
  2. افتح مشروع النص البرمجي، ثم انقر على نظرة عامة على يمين الصفحة.
  3. ضمن نطاقات Project Oauth، سجِّل كل النطاقات التي يتطلّبها النص البرمجي.
  4. في رمز تطبيق الاتصال، أنشئ رمزًا مميزًا للدخول عبر OAuth إلى نص برمجي لاستدعاء واجهة برمجة التطبيقات. وهذا ليس رمزًا مميزًا تستخدمه واجهة برمجة التطبيقات نفسها، بل يتطلب رمزًا برمجيًا عند التنفيذ. ويجب إنشاؤه باستخدام معرِّف عميل المشروع على Google Cloud ونطاقات النص البرمجي التي سجّلتها.

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

الخطوة 4: إجراء طلب script.run

بعد إعداد تطبيق الاتصال، يمكنك إجراء scripts.run مكالمات. يتكون كل طلب بيانات من واجهة برمجة التطبيقات من الخطوات التالية:

  1. أنشئ طلب واجهة برمجة تطبيقات باستخدام رقم تعريف النص البرمجي واسم الدالة وأي معلّمات مطلوبة.
  2. وعليك إجراء طلب scripts.run وتضمين رمز OAuth المميز للنص البرمجي الذي أنشأته في الرأس (في حال استخدام طلب أساسي في POST) أو استخدام كائن بيانات اعتماد تم إنشاؤه باستخدام نطاقات النص البرمجي.
  3. يمكنك السماح بإنهاء النص البرمجي. تستغرق النصوص البرمجية مدة تصل إلى ست دقائق من وقت التنفيذ، لذا يجب أن يسمح تطبيقك بذلك.
  4. عند الانتهاء، يمكن أن تعرض دالة النص البرمجي قيمة، والتي تعرضها واجهة برمجة التطبيقات مرة أخرى إلى التطبيق إذا كانت القيمة هي نوع مسموح به.

يمكنك الاطّلاع على أمثلة على طلبات البيانات من واجهة برمجة التطبيقات script.run أدناه.

أمثلة على طلبات البيانات من واجهة برمجة التطبيقات

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

النص البرمجي المستهدف

تستخدم الدالة في هذا النص البرمجي واجهة برمجة تطبيقات Drive.

وعليك تفعيل Drive API في المشروع الذي يستضيف النص البرمجي.

بالإضافة إلى ذلك، يجب أن ترسل تطبيقات الاتصال بيانات اعتماد OAuth التي تتضمن نطاق Drive التالي:

  • https://www.googleapis.com/auth/drive

تستخدم أمثلة التطبيقات هنا مكتبات Google لإنشاء عناصر بيانات اعتماد لبروتوكول OAuth باستخدام هذا النطاق.

/**
 * Return the set of folder names contained in the user's root folder as an
 * object (with folder IDs as keys).
 * @return {Object} A set of folder names keyed by folder ID.
 */
function getFoldersUnderRoot() {
  const root = DriveApp.getRootFolder();
  const folders = root.getFolders();
  const folderSet = {};
  while (folders.hasNext()) {
    const folder = folders.next();
    folderSet[folder.getId()] = folder.getName();
  }
  return folderSet;
}

لغة Java


/**
 * Create a HttpRequestInitializer from the given one, except set
 * the HTTP read timeout to be longer than the default (to allow
 * called scripts time to execute).
 *
 * @param {HttpRequestInitializer} requestInitializer the initializer
 *                                 to copy and adjust; typically a Credential object.
 * @return an initializer with an extended read timeout.
 */
private static HttpRequestInitializer setHttpTimeout(
    final HttpRequestInitializer requestInitializer) {
  return new HttpRequestInitializer() {
    @Override
    public void initialize(HttpRequest httpRequest) throws IOException {
      requestInitializer.initialize(httpRequest);
      // This allows the API to call (and avoid timing out on)
      // functions that take up to 6 minutes to complete (the maximum
      // allowed script run time), plus a little overhead.
      httpRequest.setReadTimeout(380000);
    }
  };
}

/**
 * Build and return an authorized Script client service.
 *
 * @param {Credential} credential an authorized Credential object
 * @return an authorized Script client service
 */
public static Script getScriptService() throws IOException {
  Credential credential = authorize();
  return new Script.Builder(
      HTTP_TRANSPORT, JSON_FACTORY, setHttpTimeout(credential))
      .setApplicationName(APPLICATION_NAME)
      .build();
}

/**
 * Interpret an error response returned by the API and return a String
 * summary.
 *
 * @param {Operation} op the Operation returning an error response
 * @return summary of error response, or null if Operation returned no
 * error
 */
public static String getScriptError(Operation op) {
  if (op.getError() == null) {
    return null;
  }

  // Extract the first (and only) set of error details and cast as a Map.
  // The values of this map are the script's 'errorMessage' and
  // 'errorType', and an array of stack trace elements (which also need to
  // be cast as Maps).
  Map<String, Object> detail = op.getError().getDetails().get(0);
  List<Map<String, Object>> stacktrace =
      (List<Map<String, Object>>) detail.get("scriptStackTraceElements");

  java.lang.StringBuilder sb =
      new StringBuilder("\nScript error message: ");
  sb.append(detail.get("errorMessage"));
  sb.append("\nScript error type: ");
  sb.append(detail.get("errorType"));

  if (stacktrace != null) {
    // There may not be a stacktrace if the script didn't start
    // executing.
    sb.append("\nScript error stacktrace:");
    for (Map<String, Object> elem : stacktrace) {
      sb.append("\n  ");
      sb.append(elem.get("function"));
      sb.append(":");
      sb.append(elem.get("lineNumber"));
    }
  }
  sb.append("\n");
  return sb.toString();
}

public static void main(String[] args) throws IOException {
  // ID of the script to call. Acquire this from the Apps Script editor,
  // under Publish > Deploy as API executable.
  String scriptId = "ENTER_YOUR_SCRIPT_ID_HERE";
  Script service = getScriptService();

  // Create an execution request object.
  ExecutionRequest request = new ExecutionRequest()
      .setFunction("getFoldersUnderRoot");

  try {
    // Make the API request.
    Operation op =
        service.scripts().run(scriptId, request).execute();

    // Print results of request.
    if (op.getError() != null) {
      // The API executed, but the script returned an error.
      System.out.println(getScriptError(op));
    } else {
      // The result provided by the API needs to be cast into
      // the correct type, based upon what types the Apps
      // Script function returns. Here, the function returns
      // an Apps Script Object with String keys and values,
      // so must be cast into a Java Map (folderSet).
      Map<String, String> folderSet =
          (Map<String, String>) (op.getResponse().get("result"));
      if (folderSet.size() == 0) {
        System.out.println("No folders returned!");
      } else {
        System.out.println("Folders under your root folder:");
        for (String id : folderSet.keySet()) {
          System.out.printf(
              "\t%s (%s)\n", folderSet.get(id), id);
        }
      }
    }
  } catch (GoogleJsonResponseException e) {
    // The API encountered a problem before the script was called.
    e.printStackTrace(System.out);
  }
}

JavaScript

/**
 * Load the API and make an API call.  Display the results on the screen.
 */
function callScriptFunction() {
  const scriptId = '<ENTER_YOUR_SCRIPT_ID_HERE>';

  // Call the Apps Script API run method
  //   'scriptId' is the URL parameter that states what script to run
  //   'resource' describes the run request body (with the function name
  //              to execute)
  try {
    gapi.client.script.scripts.run({
      'scriptId': scriptId,
      'resource': {
        'function': 'getFoldersUnderRoot',
      },
    }).then(function(resp) {
      const result = resp.result;
      if (result.error && result.error.status) {
        // The API encountered a problem before the script
        // started executing.
        appendPre('Error calling API:');
        appendPre(JSON.stringify(result, null, 2));
      } else if (result.error) {
        // The API executed, but the script returned an error.

        // Extract the first (and only) set of error details.
        // The values of this object are the script's 'errorMessage' and
        // 'errorType', and an array of stack trace elements.
        const error = result.error.details[0];
        appendPre('Script error message: ' + error.errorMessage);

        if (error.scriptStackTraceElements) {
          // There may not be a stacktrace if the script didn't start
          // executing.
          appendPre('Script error stacktrace:');
          for (let i = 0; i < error.scriptStackTraceElements.length; i++) {
            const trace = error.scriptStackTraceElements[i];
            appendPre('\t' + trace.function + ':' + trace.lineNumber);
          }
        }
      } else {
        // The structure of the result will depend upon what the Apps
        // Script function returns. Here, the function returns an Apps
        // Script Object with String keys and values, and so the result
        // is treated as a JavaScript object (folderSet).

        const folderSet = result.response.result;
        if (Object.keys(folderSet).length == 0) {
          appendPre('No folders returned!');
        } else {
          appendPre('Folders under your root folder:');
          Object.keys(folderSet).forEach(function(id) {
            appendPre('\t' + folderSet[id] + ' (' + id + ')');
          });
        }
      }
    });
  } catch (err) {
    document.getElementById('content').innerText = err.message;
    return;
  }
}

Node.js

/**
 * Call an Apps Script function to list the folders in the user's root Drive
 * folder.
 *
 */
async function callAppsScript() {
  const scriptId = '1xGOh6wCm7hlIVSVPKm0y_dL-YqetspS5DEVmMzaxd_6AAvI-_u8DSgBT';

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  // Get credentials and build service
  // TODO (developer) - Use appropriate auth mechanism for your app
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const script = google.script({version: 'v1', auth});

  try {
    // Make the API request. The request object is included here as 'resource'.
    const resp = await script.scripts.run({
      auth: auth,
      resource: {
        function: 'getFoldersUnderRoot',
      },
      scriptId: scriptId,
    });
    if (resp.error) {
      // The API executed, but the script returned an error.

      // Extract the first (and only) set of error details. The values of this
      // object are the script's 'errorMessage' and 'errorType', and an array
      // of stack trace elements.
      const error = resp.error.details[0];
      console.log('Script error message: ' + error.errorMessage);
      console.log('Script error stacktrace:');

      if (error.scriptStackTraceElements) {
        // There may not be a stacktrace if the script didn't start executing.
        for (let i = 0; i < error.scriptStackTraceElements.length; i++) {
          const trace = error.scriptStackTraceElements[i];
          console.log('\t%s: %s', trace.function, trace.lineNumber);
        }
      }
    } else {
      // The structure of the result will depend upon what the Apps Script
      // function returns. Here, the function returns an Apps Script Object
      // with String keys and values, and so the result is treated as a
      // Node.js object (folderSet).
      const folderSet = resp.response.result;
      if (Object.keys(folderSet).length == 0) {
        console.log('No folders returned!');
      } else {
        console.log('Folders under your root folder:');
        Object.keys(folderSet).forEach(function(id) {
          console.log('\t%s (%s)', folderSet[id], id);
        });
      }
    }
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

لغة Python

from __future__ import print_function

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def main():
    """Runs the sample.
    """
    # pylint: disable=maybe-no-member
    script_id = '1VFBDoJFy6yb9z7-luOwRv3fCmeNOzILPnR4QVmR0bGJ7gQ3QMPpCW-yt'

    creds, _ = google.auth.default()
    service = build('script', 'v1', credentials=creds)

    # Create an execution request object.
    request = {"function": "getFoldersUnderRoot"}

    try:
        # Make the API request.
        response = service.scripts().run(scriptId=script_id,
                                         body=request).execute()
        if 'error' in response:
            # The API executed, but the script returned an error.
            # Extract the first (and only) set of error details. The values of
            # this object are the script's 'errorMessage' and 'errorType', and
            # a list of stack trace elements.
            error = response['error']['details'][0]
            print(f"Script error message: {0}.{format(error['errorMessage'])}")

            if 'scriptStackTraceElements' in error:
                # There may not be a stacktrace if the script didn't start
                # executing.
                print("Script error stacktrace:")
                for trace in error['scriptStackTraceElements']:
                    print(f"\t{0}: {1}."
                          f"{format(trace['function'], trace['lineNumber'])}")
        else:
            # The structure of the result depends upon what the Apps Script
            # function returns. Here, the function returns an Apps Script
            # Object with String keys and values, and so the result is
            # treated as a Python dictionary (folder_set).
            folder_set = response['response'].get('result', {})
            if not folder_set:
                print('No folders returned!')
            else:
                print('Folders under your root folder:')
                for (folder_id, folder) in folder_set.items():
                    print(f"\t{0} ({1}).{format(folder, folder_id)}")

    except HttpError as error:
        # The API encountered a problem before the script started executing.
        print(f"An error occurred: {error}")
        print(error.content)


if __name__ == '__main__':
    main()

القيود

هناك بعض القيود على واجهة برمجة التطبيقات لبرمجة التطبيقات:

  1. مشروع مشترك على السحابة الإلكترونية: يجب أن يشارك النص البرمجي الذي يتم الاتصال به وتطبيق الاتصال في مشروع على السحابة الإلكترونية. يجب أن يكون مشروع Google Cloud مشروعًا عاديًا على Google Cloud، فإن المشاريع التلقائية التي يتم إنشاؤها لمشاريع "برمجة التطبيقات" غير كافية. ويمكن أن يكون المشروع العادي على السحابة الإلكترونية مشروعًا جديدًا أو مشروعًا حاليًا.

  2. المعلَمات الأساسية وأنواع العرض. ولا يمكن لواجهة برمجة التطبيقات تمرير العناصر الخاصة ببرمجة التطبيقات أو عرضها (مثل المستندات وBlobs والتقاويم وملفات Drive وما إلى ذلك) إلى التطبيق. لا يمكن تمرير سوى الأنواع الأساسية، مثل السلاسل والمصفوفات والعناصر والكائنات والأرقام المنطقية وعرضها.

  3. نطاقات OAuth. ولا يمكن لواجهة برمجة التطبيقات سوى تنفيذ النصوص البرمجية التي تحتوي على نطاق واحد مطلوب على الأقل. وهذا يعني أنه لا يمكنك استخدام واجهة برمجة التطبيقات لاستدعاء نص برمجي لا يتطلّب تفويضًا لخدمة واحدة أو أكثر.

  4. لا تتوفّر أي مشغّلات.لا يمكن لواجهة برمجة التطبيقات إنشاء مشغّلات لبرمجة التطبيقات.