#65 【解説】連絡先に一括登録する
以下の記事で、連絡先（Google コンタクト）に一括登録するプログラムを作成しました。このプログラムが、どんな処理をしているのかについて説明します。
この記事は、プログラムを作成し、上記の紹介記事を公開した後に改めて作成しているものです。
どんな API をつかった？
Contacts Service
今回のプログラムでは、「Contacts Service」という API を使用しました。
しかしながら、上記 URL にアクセスすると、下図のように「Contacts Service」のそれぞれの説明の後ろには 🚫 のマークが付されいます。
この 🚫 のマークは、Deprecated（非推奨）を意味するもので、下図のように「Contacts Service」は使わずに、「Advanced People Service」を使うように案内されています。
Deprecated. Instead, use the People API advanced service
既に、後継の API が提供されているのであれば、そちらを上に表示しておけばいいのに、と思ったり…
非推奨の API については、以下のページで説明されており、Google 側としては事前に案内した上での仕様変更だったようです。
この「Contacts Service」については、以下 URL で 2022/01/19 に廃止（turned down）されたと説明されていますが、現状ではまだ動作しているみたいで、完全に利用できなくなるのはいつなのかはよくわかりません。
「Contacts Service」が非推奨の API であることは理解して使いましたが、非推奨どころか廃止とアナウンスされているものだったことがわかり、本来は新規で作成するプログラムで使うべき API ではなかったことがわかりました。ちょっと、反省・後悔… 😖
Advanced People Service
後継となる API の「Advanced People Service」については、以下 URL で説明が行われています。
また改めて、People API を使ってプログラムを作り直してみようと思いますが、今回はこの People API については言及しません。
プログラムの説明
今回作成したプログラムは、コメントなどを含めて 51行となっています。
スプレッドシートにメニューを追加する onOpen関数と、実際に連絡先のスイカを行っている addContact関数の二つで構成されています。
冒頭の宣言部分
"use strict"; // 変数の宣言を強要する
/** @OnlyCurrentDoc */ // 他のファイルにはアクセスしない関数の上部にある 2行は、おまじないのような感じですが、それぞれコメントにも記載してあるように、プログラムの動作に直接関係するものではありません。
前者はプログラムを記述する際に、変数の宣言を強要するなどして、意図しないトラブルを防ごうとしているものです。
後者は、以下 URL の記事でも説明していますが、GAS のプログラムを実行する際に権限の確認を求められますが、そのときにどこまでのデータにアクセスするのかを制限しているものです。今回の場合、他のスプレッドシートにはアクセスしないことを宣言しています。
onOpen関数
この関数は、プログラムの動作には直接関係のないものです。 Google スプレッドシートのメニューに、「連作先に追加」メニューを追加し、そのサブメニュー項目として「追加実行」を設定しています。
この「追加実行」を選択すると、後述の addContact 関数が実行されます。
この辺りのメニューの作り方については、コメントとしても記載しておいた以下の URL を参考にしてあります。 ※いくつものプログラムで、同様の処理を行っているので、今回のプログラムで調べたというよりは、今回もこの URL からコピペした、というのが正しい。
実際のプログラムは、以下のような感じになっています。コメントで説明している処理を、順に行っています。
function onOpen() {
let ui = SpreadsheetApp.getUi(); // Uiクラスを取得する
let menu = ui.createMenu('連絡先に追加'); // Uiクラスからメニューを作成する
menu.addItem('追加実行', 'addContact'); // メニューにアイテムを追加する
menu.addToUi(); // メニューをUiクラスに追加する
}プログラムの使い勝手としてはメニューから処理を実行できた方がいいのですが、なかった場合には、「拡張機能」→「Apps Script」でスクリプトエディタを開いて、addContact 関数を実行することになります。
もしくは、メニューと同様の動作としては、スプレッドシート上に「図形描画」で作成したボタンのようなものを配置しておき、
そのボタンに実行したいプログラムの関数（スクリプト）を割り当てておくことで、同様の効果が得られます。
メニューとボタンのどちらを使用するかは、好みな部分もあるかと思いますが、今回のプログラムの場合、所属させる連絡先グループの数を任意に設定できるようにしてあるため、ボタンを配置する場所が確保しづらいと考えて、メニューによる実行を選択しました。
1行目の行の高さを変更して、1行目に配置するのもいいかもしれません。
addContact関数
この関数が、このプログラムの中心的な部分です。
可読性を向上させるために、挿入してある空行（何もないただの改行）や、コメントだけの行、動作確認のためにログを記録している部分などもあり、実質的な処理は更に少なくなります。
下図は、1/9 時点のプログラムの addContact関数について、流れ図を作成したものです。各記号に赤字で付してあるのは、対応するプログラムの行番号です。
if 文の終わりの } は、流れ図中には表記してありません。for 文の終わりの } は表記してあります。
関数の宣言（21行目）と、終わりの }（51行目）についても、流れ図には表記してありません。
console.log() によって、動作確認のためにログを記録している部分（29行目、40行目）も、処理には直接関係ないため、流れ図に表記してありません。
実際にプログラムを作成したときには、このような流れ図を作成してからプログラミングしたわけではありませんが、このような処理の流れを頭の中でイメージして作成していました。
引継ぎなど、保守性を高めようとするのであれば、プログラム中にコメントで説明を残したり、このような資料を作成しておくといいんじゃないかと思います。
今回のプログラムで注意するポイントは、登録しようとしている連絡先（メールアドレス）や連絡先グループが既に登録されているかをチェックしています。既に登録されている場合には、既存のデータを用いて処理するようにしています。このような判断を行わないと、同じ名前の連絡先や連絡先グループが複数作成されてしまうことになってしまいます。
45行目の 3秒間のウエイト処理については、「Contacts Service」が前述のような状況の API だからなのか、原因がよくわからないエラーが発生してしまうことがありました。対応として、このようなウエイト処理を追加したら動作が安定したので、このような状態となっています。 ※3秒の根拠はありません。
まとめ
このプログラムを教師が使用するだけでなく、生徒（児童生徒）にも使用させる場合には、生徒にも GAS のプログラムの初回実行時に行わなければならない権限の確認（以下 URL を参照）についても、説明しなければなりません。
この辺りは、生徒の状況に応じて考えるしかないんだろうな、と思います。このプログラムを使わない場合には、一つずつ手作業で追加するか、Google が提供する標準的なインポート操作（以下 URL のヘルプ記事）によって追加する、のどちらかで対応するのもいいかと思います。
最後に…
今回のプログラムは、この説明記事を書くために確認したことで、非推奨どころか、既に廃止扱いとなっている API を用いてしまったものであることがわかりました。
前述したように、日を改めて、後継の API である People API を用いたプログラムとして作り直してみようと考えています。
追記：2023/01/11
People API で作り直したプログラムを、↓ の記事で公開しました。機能的には同じです。
この記事が気に入ったらサポートをしてみませんか？