Google Apps Script API は、
scripts.run
メソッド
リモートから特定の Apps Script 関数を実行します。この方法を使用できます
呼び出し元アプリケーションで、スクリプト プロジェクトのいずれかで関数を実行する
レスポンスを受信します。
要件
呼び出し元のアプリケーションで
scripts.run
メソッドを呼び出します。必要なこと:
スクリプト プロジェクトを API 実行可能ファイルとしてデプロイします。Google Chat では 必要に応じてプロジェクトのデプロイ、デプロイ解除、再デプロイを行います。
適切なスコープの OAuth トークンを実行用に指定します。 この OAuth トークンはすべてのスコープを網羅する必要があります 使用されるものだけではなく、スクリプトが使用します。詳しくは、 認可スコープの完全なリスト を渡しています。
スクリプトと呼び出し元アプリケーションの OAuth2 クライアントが共通の Google Cloud プロジェクトを共有している。 Cloud プロジェクトは標準の Cloud プロジェクトである必要があります。 Apps Script プロジェクト用に作成されたデフォルトのプロジェクトだけでは不十分です。新しい標準 Cloud プロジェクトまたは既存の標準プロジェクトを使用できます。
Google Apps Script API を有効にする 権限があります。
scripts.run
メソッド
scripts.run
メソッドを実行するにはキー識別情報が必要です。
- スクリプト プロジェクトの ID。
- 関数の名前 必要があります。
- パラメータのリスト 関数で必要な値があれば、その値を返します。
また、開発モードで実行するようにスクリプトを構成することもできます。
このモードは、最後に保存されたスクリプト プロジェクトのバージョンで実行されます。
最新のデプロイバージョンではなくこれを行うには、
devMode
ブール値の
リクエスト本文
宛先: true
。開発モードでスクリプトを実行できるのは、そのスクリプトのオーナーのみです。
パラメータのデータ型を処理する
Apps Script API の使用
scripts.run
メソッド
通常は関数パラメータとして Apps Script にデータを送信し、
データを関数の戻り値として返すことができます。この API は
基本型(文字列、配列、オブジェクト、数値、ブール値)を持つことができます。これらの
JavaScript の基本的な型に似ています。より複雑
Document などの Apps Script オブジェクト
または Sheet を
API でスクリプト プロジェクトから読み取ることができます。
呼び出し側のアプリケーションが、
Java では、パラメータを汎用オブジェクトのリストまたは配列として渡します。
対応しています。多くの場合、単純なルールを適用する
自動的に変換されます。たとえば、1 対 1 の
パラメータとして、Java の Double
、Integer
、Long
オブジェクトを指定できます。
パラメータ化できます。
API が関数のレスポンスを返すときに、多くの場合、 正しい型に変換する必要があります。以下に例を示します。 Java ベースの例:
- API から Java アプリケーションに返される数値は、
java.math.BigDecimal
オブジェクト。このオブジェクトは、必要に応じて 必要に応じてDoubles
型またはint
型を使用します。 Apps Script 関数が文字列の配列を返す場合、 レスポンスを
List<String>
オブジェクトにキャストします。List<String> mylist = (List<String>)(op.getResponse().get("result"));
Bytes
の配列を返す場合は、 Apps Script 関数内で配列を base64 文字列としてエンコードし、 代わりにその文字列を返します。return Utilities.base64Encode(myByteArray); // returns a String.
以下のコードサンプルの例では、 API レスポンスを解釈する方法を学びます。
一般的な手順
ここでは、Apps Script API の一般的な使用手順について説明します。 Apps Script 関数を実行します。
ステップ 1: 共通の Cloud プロジェクトを設定する
スクリプトと呼び出し元アプリケーションの両方が同じ できます。この Cloud プロジェクトは、既存のプロジェクトか、 新しいプロジェクトを作成することをおすすめします。クラウド プロジェクトを用意したら、 使用するスクリプト プロジェクトを切り替える必要があります。
ステップ 2: API 実行可能ファイルとしてスクリプトをデプロイする
- 使用する関数がある Apps Script プロジェクトを開きます。
- 右上の [デプロイ] > [新しいデプロイ] をクリックします。
- 表示されたダイアログで、[デプロイタイプを有効にする]
をクリックします。 > [API Executable] を選択します。
- [アクセスできるユーザー]にあるプルダウン メニューで、 Apps Script API を使用してスクリプトの関数を呼び出すことができます。
- [デプロイ] をクリックします。
ステップ 3: 呼び出し元アプリケーションを構成する
呼び出し元のアプリケーションで Apps Script API を有効にして、OAuth を確立する必要がある 認証情報を使わずに済みますCloud プロジェクトへのアクセス権が必要です。 できます。
- 呼び出し元のアプリケーションとスクリプトが使用する Cloud プロジェクトを構成します。 手順は次のとおりです。 <ph type="x-smartling-placeholder">
- スクリプト プロジェクトを開き、左側の [概要]
をクリックします。
- [プロジェクト OAuth スコープ] で、プロジェクト 指定します。
呼び出し元のアプリケーション コードで、OAuth アクセス トークンのスクリプトを生成します。 あります。これは API 自体が使用するトークンではなく、 必要な引数を指定します。まず、 Cloud プロジェクトのクライアント ID と記録したスクリプト スコープ。
Google クライアント ライブラリを使用すると、 トークンの作成とアプリケーションの OAuth の処理を支援します。 通常は、代わりに上位レベルの「認証情報」を構築できます。オブジェクト スクリプトスコープを使用します詳しくは、 例については、Apps Script API クイックスタート 認証情報オブジェクトを構築する方法です。
ステップ 4: script.run
リクエストを行う
呼び出し元アプリケーションの構成が完了したら、
scripts.run
呼び出し。API ごとに
コールは以下の手順で構成されます。
- API リクエストを作成する スクリプト ID、関数名、必要なすべての あります。
scripts.run
を作成します。 使用してスクリプトの OAuth トークンを呼び出し、 ヘッダー(基本的なPOST
リクエストを使用する場合)、または認証情報オブジェクトを使用する スコープを使用してビルドします。- スクリプトの実行が完了するまで待ちます。スクリプトの実行には最大で 6 分間かかるので、アプリケーションはこれを考慮する必要があります。
- 終了時にスクリプト関数は値を返し、API はその値を 値がサポートされているタイプであれば、アプリケーションに返されます。
script.run
API 呼び出しの例をご覧ください。
ご覧ください
API リクエストの例
次の例は、Google Cloud コンソールで Apps Script API の実行リクエストを行う方法を示しています。
さまざまな言語のリストを出力する Apps Script 関数を呼び出して、
ルート ディレクトリに保存されます。Apps Script プロジェクトのスクリプト ID
関数を格納するファイルを指定します。
ENTER_YOUR_SCRIPT_ID_HERE
。この例は、
対応する Google API クライアント ライブラリ
対応しています。
ターゲット スクリプト
このスクリプトの関数は、Drive API を使用します。
次の場所で Drive API を有効にする必要があります。 プロジェクトを作成します。
さらに、呼び出し元アプリケーションは、 次のドライブ スコープ:
https://www.googleapis.com/auth/drive
ここのサンプル アプリケーションでは、Google クライアント ライブラリを使用して、 認証情報オブジェクトを返します。
/**
* 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()
制限事項
Apps Script API にはいくつかの制限があります。
共通の Cloud プロジェクト。呼び出されるスクリプトと Cloud プロジェクトを共有する必要があります。Cloud プロジェクトは 標準 Cloud プロジェクト Apps Script プロジェクト用に作成されたデフォルトのプロジェクトだけでは不十分です。「 新しいプロジェクトまたは既存のプロジェクトになります。
基本的なパラメータと戻り値の型。API が渡すことも、返すこともできない Apps Script 固有のオブジェクト(Documents、 blob カレンダー、 ドライブのファイルなど)を 説明します。基本的な型(文字列、配列、オブジェクト、数値、 ブール値を渡して返すことができます。
OAuth スコープ。API で実行できるスクリプトは、少なくとも 必要ありません。つまり、API を使用してスクリプトを呼び出すことはできません。 認証を必要としない場合があります。
トリガーなし。この API では Apps Script を作成できません。 トリガー。