リンクの添付ファイルを Classroom アドオンの添付ファイルにアップグレードする

教師がサードパーティのコンテンツを Classroom に追加する方法の 1 つは、課題の作成ページにリンクをリンクの添付ファイルとして貼り付けることです。教師がこれまで使い慣れている機能をさらに強化するために、教師がリンクの添付ファイルをアドオンの添付ファイルにアップグレードできるようにアドオンを構成できるようになりました。

概要

この機能を使用してアドオンを構成すると、教師が課題の作成ページにリンクの添付ファイルを貼り付ける際に、アドオンの添付ファイルへのリンクをアップグレードするよう求めるメッセージが表示されます。アドオンがすでにインストールされている場合にのみ、教師に対してインストールを求めるメッセージが表示されます。

教師がリンクをアドオンの添付ファイルにアップグレードすることに同意すると、次のクエリ パラメータでリンク アップグレード iframe が起動します。

  • courseId
  • itemId（postId から変更）
  • itemType（新規）
  • addOnToken
  • login_hint または hd
  • urlToUpgrade（新規）

最初の 4 つのクエリ パラメータは、アタッチメント ディスカバリ iframe で起動されたクエリ パラメータをミラーリングします。urlToUpgrade クエリ パラメータは新しく、アドオン アタッチメントの作成方法を評価するのに役立ちます。その後、他のクエリ パラメータを使用してユーザーがログインしているかどうかを確認し、itemType の値に基づいて courseWork、courseWorkMaterials、または announcements の CreateAddOnAttachment メソッドを呼び出します。iframe 内で読み込み画面を表示して、アドオンの添付ファイルが作成されていることを教師に示すことができます。

アドオンの添付ファイルが作成されると iframe が閉じ、教師は通常どおり課題の添付ファイルを表示できます。

技術的な実装の詳細

このセクションでは、この機能の重要な技術的詳細について説明します。

urlToUpgrade クエリ パラメータを読み取る

urlToUpgrade クエリ パラメータは、リンク アップグレード iframe に渡される際に URI エンコードされます。URL を元の形式で取得するには、URL をデコードする必要があります。たとえば、JavaScript を使用している場合は、decodeURIComponent() 関数を使用できます。

この機能で最適なユーザー エクスペリエンスを実現するには、アドオンの添付ファイルが正常に作成されたら postMessage を送信します。iframe が閉じます。詳しくは、iframe 実装の詳細ページをご覧ください。

構成の詳細

この機能をアドオンに統合するには、次の構成が必要です。

  • リンク アップグレード iframe の URL: 教師がアップグレードに同意したときに iframe に表示される URL です。

  • Classroom が検出してアップグレードを試みる URL パターン: URL パターンは、ホストと複数のパス プレフィックスで構成できます。

    • 複数の URL パターンを指定できます。
    • パスの接頭辞を指定しない場合は、ホストに一致する URL がアップグレードされます。
    • アップグレードできるのは https スキームの URL のみです。
    • URL パターンに localhost を含めることはできません。
    • パスの接頭辞にクエリ パラメータや URL フラグメントを含めることはできません。
    • 現時点では、パスの接頭辞ではワイルドカードを使用できますが、ホストではサポートされません。
      • example.com は有効なホストで、/foo と /bar/*/baz は有効なパス接頭辞です。
      • example.*.host.com は有効なホストではありません。
    • パス接頭辞のコンポーネント間のワイルドカードは、1 つのコンポーネントにのみ一致し、スラッシュで区切られた複数のコンポーネントには一致しません。ホスト example.com とパス接頭辞 /bar/*/baz を含む URL パターンについて考えてみましょう。
      • https://example.com/bar/123/baz は、URL パターンに対して有効な一致です。
      • https://example.com/bar/123/baz/456/789 は、URL パターンに対して有効な一致です。
      • パスの接頭辞のワイルドカードが /123/456/ と一致しないため、https://example.com/bar/123/456/baz は URL パターンに対して有効な一致ではありません。

開発プロセス

classroom-link-upgrade-external@google.com にメールを送信して、テスト アドオンまたは本番環境アドオンのリンク アップグレードの iframe の URL と URL パターンを送信します。

まず、限定公開アドオンと、所有するテスト環境または開発環境の構成を指定できます。Classroom チームは、本番環境の構成を有効にする前に、これらのテスト構成を有効にして、デモドメインでフローをテストできるようにします。構成が有効になると、返信メールが届きます。localhost を使用する URL パターンは、この機能ではサポートされていません。

メールの形式に次の内容を含めます。

Google Cloud Project number: GCP_PROJECT_NUMBER

Link Upgrade iframe URL: LINK_UPGRADE_IFRAME_URL

URL Patterns:
- Host:HOST_1
- Path prefixes:
  - PATH_PREFIX_1
  - PATH_PREFIX_2

- Host:HOST_2
- Path prefixes:
  - PATH_PREFIX_3
  - PATH_PREFIX_4

// add more hosts and path prefixes as needed

次のように置き換えます。

  • GCP_PROJECT_NUMBER: アドオンが関連付けられている Google Cloud プロジェクトの番号。
  • LINK_UPGRADE_IFRAME_URL は、リンクのアップグレード iframe で開く URL です。
  • HOST_1: Classroom が検出するホスト。 https スキームのみがサポートされています。
  • PATH_PREFIX_1 と PATH_PREFIX_2: Classroom が検出してアップグレードを試みる、HOST_1 に関連付けられたパス接頭辞。
  • HOST_2: Classroom が検出するホスト。 https スキームのみがサポートされています。
  • PATH_PREFIX_3、PATH_PREFIX_4: Classroom が検出してアップグレードを試みる、HOST_2 に関連付けられたパス接頭辞。

この機能を実装する際は、次のヒントを参考にしてください。

教師の余分な作業を回避

iframe を使用して、必要に応じてログインを容易にしたり、読み込みインジケーターを表示したりすることを強くおすすめします。優れたユーザー エクスペリエンスのために、貼り付けたリンクをアドオンの添付ファイルにアップグレードすることに同意した後は、教師が追加情報の入力を求められることはありません。ただし、アドオンでこれが不可能な場合は、リンク アップグレード iframe を使用して、必要な追加情報を収集できます。リンクをアップグレードできない場合やエラーが発生した場合は、iframe を使用して教師に通知することもできます。

アクセスに関するユーザー フレンドリーなエラー メッセージを含める

アクセス権のないリンクを教師が貼り付けてアップグレードした場合は、iframe にユーザー フレンドリーなエラー メッセージを表示して、教師が問題を認識できるようにします。iframe は、コンテンツにアクセスするための適切な権限を教師に付与するためにも使用できます。