Apps Script API ile İşlevler Yürütme

Google Apps Script API, belirli bir Apps Komut Dosyası işlevini uzaktan yürüten bir scripts.run yöntemi sağlar. Komut dosyası projelerinizden birindeki bir işlevi uzaktan çalıştırmak ve yanıt almak için bu yöntemi çağrı yapan bir uygulamada kullanabilirsiniz.

Koşullar

Bir çağrı uygulamasının scripts.run yöntemini kullanabilmesi için aşağıdaki gereksinimleri karşılamanız gerekir. Aşağıdakileri yapmanız gerekir:

  • Komut dosyası projesini yürütülebilir bir API olarak dağıtın. Gerektiğinde projeleri dağıtabilir, kaldırabilir ve yeniden dağıtabilirsiniz.

  • Yürütme işlemi için doğru kapsamlı bir OAuth jetonu sağlayın. Bu OAuth jetonu, yalnızca çağrılan işlev tarafından kullanılanları değil, komut dosyası tarafından kullanılan tüm kapsamları kapsamalıdır. Yöntem referansında yetkilendirme kapsamlarının tam listesini görebilirsiniz.

  • Komut dosyasının ve çağrı yapan uygulamanın OAuth2 istemcisinin ortak bir Google Cloud projesini paylaştığından emin olun. Cloud projesi standart bir Cloud projesi olmalıdır. Apps Komut Dosyası projeleri için oluşturulan varsayılan projeler yeterli değildir. Yeni bir standart Cloud projesini veya mevcut bir projeyi kullanabilirsiniz.

  • Cloud projesinde Google Apps Script API'yi etkinleştirin.

scripts.run yöntemi

scripts.run yönteminin çalışması için anahtar tanımlama bilgileri gerekir:

İsteğe bağlı olarak komut dosyanızı geliştirme modunda çalışacak şekilde yapılandırabilirsiniz. Bu mod, en son dağıtılan sürüm yerine komut dosyası projesinin en son kaydedilen sürümüyle çalışır. Bunun için istek gövdesindeki devMode boole değerini true olarak ayarlayın. Komut dosyasını yalnızca sahibi, geliştirme modunda çalıştırabilir.

Parametre veri türlerini işleme

Apps Script API scripts.run yöntemini kullanmak, genellikle verilerin Apps Komut Dosyası'na işlev parametreleri olarak gönderilmesini ve verilerin işlev dönüş değerleri olarak geri alınmasını içerir. API yalnızca şu temel türlerdeki değerleri alabilir ve döndürebilir: dizeler, diziler, nesneler, sayılar ve boole'ler. Bunlar, JavaScript'teki temel türlere benzer. Belge veya E-Tablo gibi daha karmaşık Apps Komut Dosyası nesneleri, API tarafından komut dosyası projesine veya projeden aktarılamaz.

Çağrı uygulamanız Java gibi güçlü bir dilde yazıldığında, parametreleri bu temel türlere karşılık gelen bir genel nesne listesi veya dizisi olarak aktarır. Birçok durumda, basit tür dönüşümleri otomatik olarak uygulayabilirsiniz. Örneğin, bir sayı parametresi alan işleve, ek işlem gerekmeden parametre olarak Java Double veya Integer ya da Long nesnesi verilebilir.

API, işlev yanıtını döndürdüğünde genellikle döndürülen değeri kullanılabilmesi için doğru türe yayınlamanız gerekir. Aşağıda, Java tabanlı bazı örnekler verilmiştir:

  • API tarafından bir Java uygulamasına döndürülen sayılar java.math.BigDecimal nesneleri olarak gelir ve gerektiğinde Doubles veya int türlerine dönüştürülmeleri gerekebilir.
  • Apps Komut Dosyası işlevi bir dize dizisi döndürürse bir Java uygulaması, yanıtı bir List<String> nesnesine yayınlar:

    List<String> mylist = (List<String>)(op.getResponse().get("result"));
    
  • Bir Bytes dizisi döndürmek istiyorsanız diziyi, Apps Komut Dosyası işlevi içinde base64 Dizesi olarak kodlamak ve onun yerine bu Dizeyi döndürmek işinize yarayabilir:

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

Aşağıdaki örnek kod örnekleri, API yanıtını yorumlama yollarını gösterir.

Genel prosedür

Aşağıda, Apps Komut Dosyası işlevlerini yürütmek için Apps Script API'yi kullanmayla ilgili genel prosedür açıklanmaktadır:

1. Adım: Ortak Cloud projesini oluşturun

Hem komut dosyanızın hem de çağrı uygulamasının aynı Cloud projesini paylaşması gerekir. Bu Cloud projesi, mevcut bir proje veya bu amaç için oluşturulmuş yeni bir proje olabilir. Cloud projeniz olduğunda komut dosyası projenizi kullanmak için değiştirmeniz gerekir.

2. Adım: Komut dosyasını yürütülebilir bir API olarak dağıtın

  1. Kullanmak istediğiniz işlevlerin bulunduğu Apps Komut Dosyası projesini açın.
  2. Sağ üstte, Deploy > New Deployment'ı (Yeni Dağıtım) tıklayın.
  3. Açılan iletişim kutusunda, Dağıtım türlerini etkinleştir > Yürütülebilir API'yi tıklayın.
  4. "Erişimi olanlar" açılır menüsünden, Apps Script API'yi kullanarak komut dosyasının işlevlerini çağırmasına izin verilen kullanıcıları seçin.
  5. Dağıt'ı tıklayın.

3. Adım: Arama uygulamasını yapılandırın

Çağrı uygulamasının kullanılabilmesi için Apps Script API'yi etkinleştirmesi ve OAuth isteklerini belirlemesi gerekir. Bunu yapmak için Cloud projesine erişiminiz olmalıdır.

  1. Çağrı uygulamanızın ve komut dosyanızın kullandığı Cloud projesini yapılandırın. Bunun için aşağıdaki adımları uygulayabilirsiniz:
    1. Cloud projesinde Apps Script API'yi etkinleştirin.
    2. OAuth izin ekranını yapılandırın.
    3. OAuth kimlik bilgilerini oluşturun.
  2. Komut dosyası projesini açın ve sol tarafta Genel bakış tıklayın.
  3. Proje OAuth kapsamları bölümüne, komut dosyasının gerektirdiği tüm kapsamları kaydedin.
  4. Çağrı uygulama kodunda, API çağrısı için komut dosyası OAuth erişim jetonu oluşturun. Bu, API'nin kullandığı bir jeton değil, komut dosyasının yürütme sırasında gerektirdiği bir jetondur. Cloud projesi istemci kimliği ve kaydettiğiniz komut dosyası kapsamları kullanılarak oluşturulmalıdır.

    Google istemci kitaplıkları, bu jetonun derlenmesine ve uygulama için OAuth'un işlenmesine büyük katkıda bulunabilir. Böylece, genellikle komut dosyası kapsamlarını kullanarak daha yüksek düzeyde bir "kimlik bilgisi" nesnesi oluşturabilirsiniz. Kapsam listesinden kimlik bilgisi nesnesi oluşturma örnekleri için Apps Script API hızlı başlangıç kılavuzlarına bakın.

4. Adım: script.run isteğinde bulunun

Çağrı uygulaması yapılandırıldıktan sonra scripts.run çağrıları yapabilirsiniz. Her API çağrısı aşağıdaki adımlardan oluşur:

  1. Komut dosyası kimliğini, işlev adını ve gerekli parametreleri kullanarak bir API isteği oluşturun.
  2. scripts.run çağrısı yapın ve başlığa oluşturduğunuz komut dosyası OAuth jetonunu ekleyin (temel POST isteği kullanıyorsanız) veya komut dosyası kapsamlarıyla oluşturduğunuz kimlik bilgisi nesnesini kullanın.
  3. Komut dosyasının çalışmayı tamamlamasına izin verin. Komut dosyalarının yürütme süresi altı dakikayı bulabilir. Bu nedenle uygulamanız buna izin vermelidir.
  4. İşlem tamamlandığında komut dosyası işlevi bir değer döndürebilir. Bu değer, desteklenen türdeyse API tarafından uygulamaya geri gönderilir.

script.run API çağrısı örneklerini aşağıda bulabilirsiniz.

API isteği örnekleri

Aşağıdaki örneklerde, çeşitli dillerde bir Apps Script API yürütme isteğinin nasıl yapılacağı gösterilmektedir. Kullanıcı kök dizinindeki klasörlerin listesini yazdırmak için Apps Komut Dosyası işlevi çağırılmaktadır. Yürütülen işlevi içeren Apps Komut Dosyası projesinin komut dosyası kimliği, ENTER_YOUR_SCRIPT_ID_HERE ile belirtildiği yerde belirtilmelidir. Örneklerde, ilgili diller için Google API İstemci kitaplıkları temel alınır.

Hedef Komut Dosyası

Bu komut dosyasındaki işlev Drive API'yi kullanıyor.

Komut dosyasını barındıran projede Drive API'yi etkinleştirmeniz gerekir.

Ayrıca çağrı uygulamaları, aşağıdaki Drive kapsamını içeren OAuth kimlik bilgilerini göndermelidir:

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

Buradaki örnek uygulamalar, bu kapsamı kullanarak OAuth için kimlik bilgisi nesneleri oluşturmak amacıyla Google istemci kitaplıklarını kullanır.

/**
 * 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

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}.{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()

Sınırlamalar

Apps Script API'nin bazı sınırlamaları vardır:

  1. Ortak bir Cloud projesi. Çağrılan komut dosyası ve çağrı yapan uygulama bir Cloud projesini paylaşmalıdır. Cloud projesi standart bir Cloud projesi olmalıdır. Apps Komut Dosyası projeleri için oluşturulan varsayılan projeler yeterli değildir. Standart Cloud projesi yeni bir proje veya mevcut bir proje olabilir.

  2. Temel parametre ve dönüş türleri. API, Apps Komut Dosyası'na özgü nesneleri (ör. Dokümanlar, Bloblar, Takvimler, Drive Dosyaları vb.) uygulamaya geçiremez veya döndüremez. Yalnızca dizeler, diziler, nesneler, sayılar ve boole'ler gibi temel türler iletilebilir ve döndürülebilir.

  3. OAuth kapsamları. API yalnızca en az bir gerekli kapsama sahip komut dosyalarını yürütebilir. Yani bir veya daha fazla hizmetin yetkilendirilmesini gerektirmeyen bir komut dosyasını çağırmak için API'yi kullanamazsınız.

  4. Tetikleyici yok.API, Apps Komut Dosyası tetikleyicileri oluşturamaz.