[go: up one dir, main page]

この記事は G Suite デベロッパーアドボケート、Wesley Chun（@wescpy）による G Suite Developers Blogの記事 "Using field masks with update requests to Google APIs" を元に翻訳・加筆したものです。詳しくは元記事をご覧ください。
　
先日、Google API に対して読み取り（GET）リクエストを呼び出す際に、フィールド マスクを使ってレスポンス ペイロードとして返されるデータ量を削減する方法を紹介しました。本日（*原文公開当時）は、フィールド マスクの別のユースケースであるアップデート リクエストについて紹介しましょう。 　
　
このシナリオでは、以前と似ているものの、少し異なる目的でフィールド マスクを利用します。この方法を使う場合、フィールド マスクはフィルターとして動作しますが、どちらかといえば、どの API フィールドをアップデートするかを制御するビットマスクのような働きになります。次の動画では、Google Sheets API と Slides API を使ったいくつかの例を挙げてアップデート フィールド マスクの使用方法について説明しています。ぜひご覧ください。 　
次に示すサンプル JSON ペイロードでは、（cell ディレクティブによって）セルの太字属性を true に設定するリクエストを行っています。その際のフィールド マスク（fields）は、リクエストを繰り返しているようにも見えます。 　
{
    "repeatCell": {
        "range": {
            "endRowIndex": 1
        },
        "cell": {
            "userEnteredFormat": {
                "textFormat": {
                    "bold": true
                }
            }
        },
        "fields": "userEnteredFormat/textFormat/bold",
    }
}

「これは冗長ではないか？」と思うかもしれません。しかし、上の例は 2 つの部分からなる点に注目してください。1）リクエストが望む変更点についてのデータを提供します。2）たとえば、1 行目のすべてのセルの userEnteredFormat/textFormat/bold 属性というような形で、フィールド マスクで何をアップデートするかを指定します。もう少し明示的に説明するために、斜体のような別のマスクを追加してみましょう。これでアップデート フィールド マスクに、太字と斜体の両方のフィールドが設定されました。 　
"fields": "userEnteredFormat/textFormat(bold,italic)"

ただし、フィールド マスクに両方の要素が存在しても、アップデート データを提供しているのは太字だけです。リクエスト本体には、italic を設定するデータは指定されていません。この場合、すべてのセルがリセットされます。つまり、セルがもともと斜体になっていれば、API リクエストの完了後に斜体が解除されます。逆に、最初からセルが斜体になっていない場合は、セルはそのままになります。この機能を使うと、あるセルの範囲を元に戻したり、以前の設定をリセットしたりする機能を実現できます。その他の例や、アップデート リクエストへのフィールド マスクの活用方法については、先ほどの動画をご覧ください。 　
　
フィールド マスクを使って API ペイロードの部分的な応答を取得する方法の詳細については、こちらの動画や 2 回シリーズの 1 回目の投稿をご覧ください。両方（読み取りおよびアップデート）のユースケースに関する総合的な記事については、Google Slides API ドキュメントのガイドをご覧ください。 ぜひフィールド マスクをお楽しみください！ 　
　
　
Posted by Eiji Kitamura - Developer Relations Team

この記事は Google Developers エキスパート、Bruce Mcpherson および Romain Vialard、G Suite デベロッパー アドボケート、Wesley Chun（@wescpy）による G Suite Developers Blog の記事 "Using Google Sheets filters in Add-ons with Google Apps Script" を元に翻訳・加筆したものです。詳しくは元記事をご覧ください。

Google Apps Script を使っているデベロッパーの皆さんは、アップデートされた Google Sheets API の豊富な機能と、最近リリースされた Advanced Sheets Service にアクセスできます。Advanced Service を使用すると、ネイティブ Apps Script オブジェクトを使用した場合と比較して、デベロッパーが現在の API 機能に（ネイティブ サポートを待つことなく）アクセスできるというメリットがあります。たとえば、Advanced Service を使うと、デベロッパーはスプレッドシート フィルタにアクセスしてアドオンを強化できます。

フィルタ機能 

Sheets API を使うと、フィルタで絞り込んだ列を取得したり、スプレッドシートに対して新しいフィルタを設定したりできます。また、Advanced Sheet Service を使うと、アドオンにフィルタを認識させ、新しいフィルタを適用してスプレッドシート UI に表示されているデータを変更できます。さらに、任意の Apps Script Advanced Service を併用することで、直接 REST API を使用する場合に必要となる UrlFetch サービスの使用や認証フローの管理なしに、スプレッドシートやその他の Google API に簡単にアクセスできるようになります。次のスニペットは、指定されたスプレッドシートのフィルタで絞り込まれた行のインデックスを返します。API ドキュメントに示されているように、Google スプレッドシートの「行を非表示」メニュー項目を使って手動で非表示にした行のリストを取得することも可能です。このコードサンプルでは、フィルタで除外された行だけを返しています。 

 function getIndexesOfFilteredRows(ssId, sheetId) {
  var hiddenRows = [];
  
  // limit what's returned from the API
  var fields = "sheets(data(rowMetadata(hiddenByFilter)),properties/sheetId)";
  var sheets = Sheets.Spreadsheets.get(ssId, {fields: fields}).sheets;  
  
  for (var i = 0; i < sheets.length; i++) {
    if (sheets[i].properties.sheetId == sheetId) {
      var data = sheets[i].data;
      var rows = data[0].rowMetadata;
      for (var j = 0; j < rows.length; j++) {
        if (rows[j].hiddenByFilter) hiddenRows.push(j);
      }
    }
  }
  return hiddenRows;
} 
コード スニペット内の fields パラメータは、Sheets API レスポンスで返される内容をアプリに関係する値のみに制限します。詳しくは、Sheets API ドキュメントのこちらのページか、フィールド マスクについての最新動画をご覧ください。

アドオンによるフィルタの使用例 

スプレッドシートには、高度なフィルタを使用するアドオンがたくさんあります。以下は良い例です。
  • Yet Another Mail Merge: スプレッドシートからメール キャンペーンを送信できるアドオンです。このアドオンは、スプレッドシートのフィルタで絞り込まれた行のみを処理します。たとえば、イベントに登録している人のリストがあり、登録者の一部しか受け付けておらず、確認メールを出したい場合を考えてみましょう。Yet Another Mail Merge とアップデートされた API を使うと、受け付けていない人を除外することができるので、アドオンはその人々に確認メールを送らずにスキップします。
  • Sankey Snip と Chord Snip: Google スプレッドシートの UI では利用できない特殊な種類のチャートを作成できるアドオンです。アドオンにフィルタを認識させると、フィルタで絞り込まれたデータがチャートとして視覚化されます。次の Chord Snip アドオンのサンプルをご覧ください。
もちろん、API を使ってスプレッドシートのフィルタの追加、更新、削除もできます。これは、特定のステータスを持つ行をすばやくユーザーに表示したい場合に便利です。ワークフローの承認アドオンを構築する場合の例をあげれば、承認待ちの行のみをユーザーに表示できます。下のスニペットは、指定されたスプレッドシートにリクエストされたフィルタを適用するものです。API ドキュメントでは、これを標準基本フィルタ オブジェクトと呼んでいます。 

function setSheetBasicFilter(ssId, BasicFilterSettings) {
  //requests is an array of batchrequests, here we only use setBasicFilter
  var requests = [
    {
      "setBasicFilter": {
        "filter": BasicFilterSettings
      }
    }
  ];
  Sheets.Spreadsheets.batchUpdate({'requests': requests}, ssId);
}

Yet Another Mail Merge などの大量メールツールは、メールの送信、オープン、クリックをトラッキングしています。トラッキング レポートはスプレッドシートのサイドバーから利用でき、オープンされたメールの数をクリックすると、自動的にフィルタが適用されて、ステータスが「opened」の行のみが表示されるようになります。


スプレッドシートに適用されるフィルタは、直接 Sheets API から制御したり、Apps Script アプリと Advanced Sheets Service を使ったアドオンから制御できます。ぜひこの機能を使って最高のユーザー エクスペリエンスを提供してください。

投稿者について 

Romain Vialard は、Google Developer エキスパートです。数年間を G Suite コンサルタントとして過ごし、現在は、Yet Another Mail Merge や Form Publisher などのアドオンを含む G Suite および Google Apps ユーザー向けの製品に注力しています。

Bruce Mcpherson は、Google Developer エキスパート、独立コンサルタント、ブロガーで、Going GAS や Google Apps Script for Beginners、Google Apps Script for Developers の作者でもあります。


Posted by Eiji Kitamura - Developer Relations Team

[この記事は Wesley Chun、G Suite デベロッパー アドボケートによる G Suite Developers Blog の記事 "Formatting cells with the Google Sheets API" を元に翻訳・加筆したものです。詳しくは元記事をご覧ください。]

今年開催された Google I/O で、新しくなった Google スプレッドシート API が発表されました（発表のすべての内容は、こちらからご覧いただけます）。アップデートされた API には、以前のバージョンでは利用できなかった多くの新機能が含まれています。たとえば、PC 版およびモバイル版スプレッドシートのユーザー インターフェース機能のうち、API からアクセスできるものが増えました。以前のバージョンの API にはなかった機能の 1 つが、スプレッドシート内のセルの書式設定です。本日の DevByte 動画では、この機能を取り上げています。


以前に公開したスプレッドシート API の動画では、リレーショナル データベースから行を読み込み、新しい Google スプレッドシートにデータを移す簡単なスクリプトについて説明しながら、プログラムから Google スプレッドシート データの書き込みや読み込みを行う方法を紹介しました。本日は、その動画のコードを使って作成したスプレッドシートを取り上げます。

スプレッドシートの書式設定を行うには、一連の JSON ペイロード形式のリクエスト コマンドを作成し、それを API に送信します。次に示すのは、リクエスト（この例では 1 つだけ）の配列からなるサンプル JavaScript オブジェクトです。これは、自動的に作成される既定のスプレッドシート（ID が 0）の先頭行を太字にします。 
{"requests": [
    {"repeatCell": {
        "range": {
            "sheetId": 0,
            "startRowIndex": 0,
            "endRowIndex": 1
        },
        "cell": {
            "userEnteredFormat": {
                "textFormat": {
                    "bold": true
                }
            }
        },
        "fields": "userEnteredFormat.textFormat.bold"
    }}
]}
ここでは、1 つ以上のリクエストが変数 requests に格納されており、スプレッドシートの ID は SHEET_IDとしています。API にリクエストを送信するには、HTTP POST で https://sheets.googleapis.com/v4/spreadsheets/{SHEET_ID}:batchUpdate に送ります。Python を使うと、次のような 1 回の呼び出しで実現できます。 
SHEETS.spreadsheets().batchUpdate(spreadsheetId=SHEET_ID,
        body=requests).execute()

動画のコードの詳細については、さらに詳しく説明しているブログ投稿をご覧ください。皆さんのご想像どおり、一番難しいのは API を呼び出す際に送信する JSON ペイロードを作成するところです。この部分は、一般的な操作のサンプルを参考にすることをおすすめします。玩具会社で顧客の注文を管理する Node.js アプリの書き方を説明している JavaScript コードラボもご覧ください。この例では、本日取り上げた玩具の注文データを使っていますが、データはリレーショナル データベース内にあります。本日の動画では、これと同等のスプレッドシートを主に取り上げていますが、また別の機会に、新しい Google スライド API とこのスプレッドシートのデータを使ってスライドを生成する方法を紹介する予定です。ご期待ください。

G Suite API を使って今後のアプリを強化するにあたって、これらのリソースをご活用いただければ幸いです。G Suite Dev Show のチャンネルを購読し、今後取り上げてほしいトピックについてお知らせください。


Posted by Eiji Kitamura - Developer Relations Team