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

Google Apps Komut Dosyası API'si bir scripts.run yöntem Google Analytics 4'teki belirli bir Apps Komut Dosyası işlevini uzaktan yürütür. Bu yöntemi kullanabilirsiniz bir çağrı uygulamasında komut dosyası projelerinizden birinde bir işlev çalıştırmak için ve yanıt alabilirsiniz.

Şartlar

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

  • Komut dosyası projesini, yürütülebilir API dosyası olarak dağıtın. Şunları yapabilirsiniz: ve gerektiğinde projeleri dağıtabilirsiniz.

  • Yürütme işlemi için doğru şekilde ayarlanmış bir OAuth jetonu sağlayın. Bu OAuth jetonu tüm kapsamları kapsamalıdır tarafından değil komut dosyası tarafından kullanılır. Bkz. yetkilendirme kapsamlarının tam listesi eklemesi gerekir.

  • Komut dosyasının ve çağrı yapan uygulamanın OAuth2 istemci ortak bir Google 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 yetersizdir. Yeni bir standart Cloud projesini veya mevcut bir projeyi kullanabilirsiniz.

  • Google Apps Komut Dosyası API'sını etkinleştirme inceleyebilirsiniz.

ziyaret edin.

scripts.run yöntemi

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

İsteğe bağlı olarak, komut dosyanızı geliştirme modunda yürütülecek şekilde yapılandırabilirsiniz. Bu mod, komut dosyası projesinin en son kaydedilen sürümüyle yürütülür tercih edebilirsiniz. Bunu, devMode boole istek gövdesi Hedef: true. Yalnızca komut dosyasının sahibi bu işlemi geliştirme modunda yürütebilir.

Parametre veri türlerini işleme

Apps Komut Dosyası API'sini kullanma scripts.run yöntem genellikle, Apps Komut Dosyası'na fonksiyon parametreleri olarak veri göndermeyi ve verileri işlev döndüren değerler olarak geri alınıyor. API yalnızca alabilir ve geri dönebilir dizeler, diziler, nesneler, sayılar ve booleler gibi temel türlerdeki değerlerdir. Bu JavaScript'teki temel türlere benzer. Daha karmaşık Doküman gibi Apps Komut Dosyası nesneleri veya Sayfa, veya API tarafından komut dosyası projesinden alınır.

Arama uygulamanız, Java, parametreleri genel nesnelerden oluşan bir liste veya dizi olarak aktarır karşılık gelecektir. Pek çok durumda, yol haritası, dönüşümleri otomatik olarak yazın. Örneğin, sayı alan bir fonksiyon parametresine bir Java Double veya Integer ya da Long nesnesi parametresini kullanabilirsiniz.

API işlev yanıtını döndürdüğünde genellikle değeri döndürülmeden önce doğru türe döndürmeniz gerekir. Aşağıda bazı örnekler verilmiştir: Java tabanlı örnekler:

  • API tarafından Java uygulamasına döndürülen sayılar java.math.BigDecimal nesnedir ve şuna dönüştürülmesi gerekebilir: Gerektiğinde Doubles veya int türü.

  • 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 bunu sizin için uygun bulabilirsiniz dizeyi Apps Komut Dosyası işlevi içinde bir base64 Dizesi olarak kodlamak ve Bunun yerine, dizeyi döndürün:

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

Aşağıdaki örnek kod örnekleri, API yanıtını yorumlamak.

Genel prosedür

Aşağıda, Apps Komut Dosyası API'sini kullanmaya ilişkin genel prosedür açıklanmaktadır. işlevini kullanın:

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

Hem komut dosyanızın hem de arama uygulamasının, aynı Cloud projesi. Bu Cloud projesi, mevcut bir proje veya bu amaçla oluşturulan yeni bir projedir. Bir Cloud projeniz olduğunda komut dosyası projenizi kullanmak için değiştirmelisiniz.

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

  1. Kullanmak istediğiniz işlevleri içeren Apps Komut Dosyası projesini açın.
  2. Sağ üstte Deploy (Dağıt) &gt; New Deployment (Yeni Dağıtım) seçeneğini tıklayın.
  3. Açılan iletişim kutusunda, Dağıtım türlerini etkinleştir'i tıklayın. &gt; Yürütülebilir API.
  4. "Erişimi olanlar" açılır menüden, hangi komut dosyasının işlevlerini Apps Komut Dosyası API'sini kullanarak çağırmasına izin verilir.
  5. Dağıt'ı tıklayın.

3. Adım: Çağrı yapan uygulamayı yapılandırın

Çağrı yapan uygulamanın Apps Script API'yi etkinleştirmesi ve OAuth oluşturması gerekir kritik önem taşır. Cloud projesine erişiminiz olmalıdır yardımcı oluyorum.

  1. Çağrı uygulamanızın ve komut dosyanızın kullandığı Cloud projesini yapılandırın. Bunu aşağıdaki adımları uygulayarak yapabilirsiniz:
    1. Cloud projesinde Apps Script API'yi etkinleştirin.
    2. OAuth izin ekranını yapılandırın.
    3. OAuth kimlik bilgileri oluşturun.
  2. Komut dosyası projesini açın ve solda Genel Bakış'ı tıklayın.
  3. Project Oauth kapsamları altında, komut dosyası gerekir.

  4. Çağrı yapan uygulamanın kodunda bir komut dosyası OAuth erişim jetonu oluşturun. öğesine dokunun. Bu, API'nin kendisinin kullandığı bir simge değil, komut dosyasının yürütülmesi sırasında gerektiğini belirtir. Projeniz için Bulut projesi istemci kimliği ve kaydettiğiniz komut dosyası kapsamları.

    Google istemci kitaplıkları bu jetonun oluşturulmasına ve uygulama için OAuth'un işlenmesine yardımcı olur. genellikle bunun yerine daha üst düzey "kimlik bilgileri" ve nesne komut dosyası kapsamlarını kullanın. Bkz. Örnekler için Apps Script API hızlı başlangıç kılavuzları kimlik bilgileri nesnesi oluşturma adımına geçelim.

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

Görüşme uygulaması yapılandırıldıktan sonra şunları yapabilirsiniz: scripts.run çağrı. Her bir API çağrısı aşağıdaki adımlardan oluşur:

  1. API isteği oluşturma komut dosyası kimliğini, işlev adını ve gerekli parametreleridir.
  2. scripts.run yapın .ZIP dosyasında oluşturduğunuz komut dosyası OAuth jetonunu üstbilgisini (temel POST isteği kullanıyorsanız) veya kimlik bilgileri nesnesini kullanın. geliştirmenizi sağlar.
  3. Komut dosyasının yürütme işlemini tamamlamasına izin verin. Komut dosyalarının tamamlanması için altı dakikalık bir yürütme süresi olduğundan uygulamanız buna izin vermelidir.
  4. İşlem tamamlandıktan sonra, komut dosyası işlevi bir değer döndürebilir. API, Değer desteklenen bir türse uygulamaya geri döner.

script.run API çağrısı örneklerini bulabilirsiniz bölümüne göz atın.

API isteği örnekleri

Aşağıdaki örnekler, Apps Komut Dosyası işlevini çağırarak her bir dosyanın listesini yazdırabilirsiniz klasörlerini içermelidir. Apps Komut Dosyası projesinin komut dosyası kimliği yürütülür işlevi içeren işlev, ENTER_YOUR_SCRIPT_ID_HERE Örnekler, Google API İstemci kitaplıkları dil.

Hedef Komut Dosyası

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

Şuradan Drive API'yi etkinleştirmeniz gerekir: barındırmak için kullanır.

Ayrıca, çağrı yapan uygulamaların şu bilgileri içeren OAuth kimlik bilgileri göndermesi gerekir: aşağıdaki Drive kapsamı:

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

Buradaki örnek uygulamalar, derleme aracı oluşturmak için kimlik bilgisi nesnelerini (ör. OAuth için kimlik bilgisi) 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;
}
target.js

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);
  }
}
Execute.java

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;
  }
}

index.js

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;
  }
}
index.js

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()
execute.py

Sınırlamalar

Apps Komut Dosyası API'sinin bazı sınırlamaları vardır:

  1. Ortak bir Cloud projesi. Çağrılan komut dosyası ve çağrı uygulamasının bir Cloud projesi paylaşması gerekir. Cloud projesi, standart Cloud projesi; Apps Komut Dosyası projeleri için oluşturulan varsayılan projeler yetersizdir. İlgili içeriği oluşturmak için kullanılan standart Cloud projesi yeni bir proje veya mevcut bir proje olabilir.

  2. Temel parametre ve dönüş türleri. API Apps Komut Dosyası'na özel nesneler (ör. Dokümanlar, Bloblar Takvimler, Drive Dosyaları vb.) bir uygulamadır. Yalnızca dizeler, diziler, nesneler, sayılar ve boole değerleri iletilebilir ve döndürülebilir.

  3. OAuth kapsamları. API yalnızca en az kapsamı seçmeye çalışın. Bu, bir komut dosyası çağırmak için API'yi kullanamayacağınız anlamına gelir Bir veya birden fazla hizmet için yetkilendirme gerektirmeyen

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