कॉन्टेंट-टाइप अटैचमेंट

यह, Classroom के ऐड-ऑन के बारे में जानकारी देने वाली सीरीज़ का चौथा लेख है.

इस लेख में, अटैचमेंट बनाने के लिए Google Classroom API के साथ इंटरैक्ट किया जाता है. इसमें, उपयोगकर्ताओं को अटैचमेंट का कॉन्टेंट देखने के लिए रास्ते उपलब्ध कराए जाते हैं. क्लास में उपयोगकर्ता की भूमिका के हिसाब से, अलग-अलग व्यू दिखते हैं. इस लेख में कॉन्टेंट-टाइप अटैचमेंट के बारे में बताया गया है. इसके लिए, छात्र-छात्राओं को कुछ भी सबमिट करने की ज़रूरत नहीं होती.

इस लेख में, आपको ये काम करने होंगे:

  • ऐड-ऑन के इन क्वेरी पैरामीटर को वापस पाना और उनका इस्तेमाल करना:
    • addOnToken: यह ऑथराइज़ेशन टोकन, अटैचमेंट डिस्कवरी व्यू को पास किया जाता है.
    • itemId: यह CourseWork, CourseWorkMaterial या Announcement के लिए यूनीक आइडेंटिफ़ायर होता है. इसमें ऐड-ऑन अटैचमेंट मिलता है.
    • itemType: यह "courseWork", "courseWorkMaterials" या "announcement" हो सकता है.
    • courseId: यह Google Classroom के उस कोर्स के लिए यूनीक आइडेंटिफ़ायर होता है जिसमें असाइनमेंट बनाया जा रहा है.
    • attachmentId: यह Google Classroom से, ऐड-ऑन अटैचमेंट को बनाने के बाद असाइन किया गया यूनीक आइडेंटिफ़ायर होता है.
  • कॉन्टेंट-टाइप अटैचमेंट के लिए, परसिस्टेंट स्टोरेज लागू करना.
  • अटैचमेंट बनाने के लिए रास्ते उपलब्ध कराना. साथ ही, Teacher View और Student View के iframe उपलब्ध कराना.
  • Google Classroom के ऐड-ऑन API को ये अनुरोध भेजना:
    • नया अटैचमेंट बनाना.
    • ऐड-ऑन का कॉन्टेक्स्ट पाना. इससे यह पता चलता है कि लॉग-इन किया हुआ उपयोगकर्ता छात्र है या शिक्षक.

इन सभी चरणों को पूरा करने के बाद, शिक्षक के तौर पर लॉग इन करने पर, Google Classroom के यूआई की मदद से असाइनमेंट में कॉन्टेंट-टाइप अटैचमेंट बनाए जा सकते हैं. क्लास में मौजूद शिक्षक और छात्र-छात्राएं भी कॉन्टेंट देख सकते हैं.

Classroom API को चालू करना

Classroom API को कॉल करने के लिए, इस चरण से शुरुआत करें. Google Cloud प्रोजेक्ट के लिए, एपीआई को चालू करना ज़रूरी है. इसके बाद ही, इसे कॉल किया जा सकता है. Google Classroom API लाइब्रेरी एंट्री पर जाएं और चालू करें को चुनें.

अटैचमेंट डिस्कवरी व्यू के क्वेरी पैरामीटर मैनेज करना

जैसा कि पहले बताया गया है, iframe में अटैचमेंट डिस्कवरी व्यू लोड करते समय, Google Classroom क्वेरी पैरामीटर पास करता है:

  • courseId: यह मौजूदा Classroom कोर्स का आईडी होता है.
  • itemId: यह CourseWork, CourseWorkMaterial या Announcement के लिए यूनीक आइडेंटिफ़ायर होता है. इसमें ऐड-ऑन अटैचमेंट मिलता है.
  • itemType: यह "courseWork", "courseWorkMaterials" या "announcement" हो सकता है.
  • addOnToken: यह टोकन, Classroom के ऐड-ऑन की कुछ कार्रवाइयों को ऑथराइज़ करने के लिए इस्तेमाल किया जाता है.
  • login_hint: यह मौजूदा उपयोगकर्ता का Google आईडी होता है.

इस लेख में, courseId, itemId, itemType, और addOnToken के बारे में बताया गया है. Classroom API को कॉल करते समय, इन्हें बनाए रखें और पास करें.

पिछले लेख के चरण की तरह, पास की गई क्वेरी पैरामीटर वैल्यू को अपने सेशन में सेव करें. अटैचमेंट डिस्कवरी व्यू को पहली बार खोलने पर, ऐसा करना ज़रूरी है. ऐसा इसलिए, क्योंकि Classroom के पास इन क्वेरी पैरामीटर को पास करने का यही एक मौका होता है.

Python

अपने Flask सर्वर की उस फ़ाइल पर जाएं जिसमें अटैचमेंट डिस्कवरी व्यू के लिए रास्ते तय किए गए हैं. अगर दिए गए उदाहरण का इस्तेमाल किया जा रहा है, तो यह फ़ाइल attachment-discovery-routes.py है. अपने ऐड-ऑन के लैंडिंग रूट (/classroom-addon अगर दिए गए उदाहरण का इस्तेमाल किया जा रहा है) में सबसे ऊपर, courseId, itemId, itemType, और addOnToken क्वेरी पैरामीटर वापस पाएं और सेव करें.

# Retrieve the itemId, courseId, and addOnToken query parameters.
if flask.request.args.get("itemId"):
    flask.session["itemId"] = flask.request.args.get("itemId")
if flask.request.args.get("itemType"):
    flask.session["itemType"] = flask.request.args.get("itemType")
if flask.request.args.get("courseId"):
    flask.session["courseId"] = flask.request.args.get("courseId")
if flask.request.args.get("addOnToken"):
    flask.session["addOnToken"] = flask.request.args.get("addOnToken")

इन वैल्यू को सिर्फ़ तब सेशन में लिखें, जब ये मौजूद हों. अगर उपयोगकर्ता, iframe बंद किए बिना बाद में अटैचमेंट डिस्कवरी व्यू पर वापस आता है, तो इन्हें फिर से पास नहीं किया जाता.

कॉन्टेंट-टाइप अटैचमेंट के लिए, परसिस्टेंट स्टोरेज जोड़ना

बनाए गए सभी अटैचमेंट का स्थानीय रिकॉर्ड होना ज़रूरी है. इससे, Classroom से मिले आइडेंटिफ़ायर का इस्तेमाल करके, शिक्षक के चुने गए कॉन्टेंट को ढूंढा जा सकता है.

Attachment के लिए, डेटाबेस स्कीमा सेट अप करें. दिए गए उदाहरण में, ऐसे अटैचमेंट दिखाए गए हैं जिनमें एक इमेज और एक कैप्शन दिखता है. Attachment में ये एट्रिब्यूट शामिल होते हैं:

  • attachment_id: यह अटैचमेंट के लिए यूनीक आइडेंटिफ़ायर होता है. इसे Classroom से असाइन किया जाता है और अटैचमेंट बनाते समय, जवाब में वापस भेजा जाता है.
  • image_filename: यह दिखाने के लिए इमेज की स्थानीय फ़ाइल का नाम होता है.
  • image_caption: यह इमेज के साथ दिखने वाला कैप्शन होता है.

Python

पिछले चरणों में, SQLite और flask_sqlalchemy के लागू करने के तरीके को बढ़ाएं.

उस फ़ाइल पर जाएं जिसमें आपने User टेबल तय की है. अगर दिए गए उदाहरण का इस्तेमाल किया जा रहा है, तो यह फ़ाइल models.py है. फ़ाइल में सबसे नीचे, User क्लास के नीचे यह कोड जोड़ें.

class Attachment(db.Model):
    # The attachmentId is the unique identifier for the attachment.
    attachment_id = db.Column(db.String(120), primary_key=True)

    # The image filename to store.
    image_filename = db.Column(db.String(120))

    # The image caption to store.
    image_caption = db.Column(db.String(120))

अटैचमेंट को मैनेज करने वाले रास्तों वाली सर्वर फ़ाइल में, नई Attachment क्लास इंपोर्ट करें.

नए रास्ते सेट अप करना

इस लेख में बताए गए चरण को पूरा करने के लिए, अपने ऐप्लिकेशन में कुछ नए पेज सेट अप करें. इनकी मदद से, उपयोगकर्ता हमारे ऐड-ऑन के ज़रिए कॉन्टेंट बना और देख सकता है.

अटैचमेंट बनाने के रास्ते जोड़ना

शिक्षक के लिए, कॉन्टेंट चुनने और अटैचमेंट बनाने के अनुरोध भेजने के लिए, पेजों की ज़रूरत होती है. शिक्षक को चुनने के लिए, कॉन्टेंट के विकल्प दिखाने के लिए, /attachment-options रूट लागू करें. आपको कॉन्टेंट चुनने और अटैचमेंट बनाने की पुष्टि करने वाले पेजों के लिए टेंप्लेट की भी ज़रूरत होती है. दिए गए उदाहरणों में इनके लिए टेंप्लेट शामिल हैं. साथ ही, इनमें Classroom API से मिले अनुरोध और जवाब भी दिखाए जा सकते हैं.

ध्यान दें कि आपके पास, नया /attachment-options पेज बनाने के बजाय, कॉन्टेंट के विकल्प दिखाने के लिए, अपने मौजूदा अटैचमेंट डिस्कवरी व्यू के लैंडिंग पेज में बदलाव करने का विकल्प भी है. हमारा सुझाव है कि इस चरण के लिए, एक नया पेज बनाएं, ताकि दूसरे लेख के चरण में लागू किए गए एसएसओ के व्यवहार को बनाए रखा जा सके. जैसे, ऐप्लिकेशन की अनुमतियां रद्द करना. ये आपके ऐड-ऑन को बनाने और टेस्ट करने में मददगार साबित होंगे.

दिए गए उदाहरण में, शिक्षक कैप्शन वाली कुछ इमेज में से कोई इमेज चुन सकता है. हमने मशहूर जगहों की चार इमेज दी हैं. इनके कैप्शन, फ़ाइल के नामों से लिए गए हैं.

Python

दिए गए उदाहरण में, यह webapp/attachment_routes.py फ़ाइल में है.

@app.route("/attachment-options", methods=["GET", "POST"])
def attachment_options():
    """
    Render the attachment options page from the "attachment-options.html"
    template.

    This page displays a grid of images that the user can select using
    checkboxes.
    """

    # A list of the filenames in the static/images directory.
    image_filenames = os.listdir(os.path.join(app.static_folder, "images"))

    # The image_list_form_builder method creates a form that displays a grid
    # of images, checkboxes, and captions with a Submit button. All images
    # passed in image_filenames will be shown, and the captions will be the
    # title-cased filenames.

    # The form must be built dynamically due to limitations in WTForms. The
    # image_list_form_builder method therefore also returns a list of
    # attribute names in the form, which will be used by the HTML template
    # to properly render the form.
    form, var_names = image_list_form_builder(image_filenames)

    # If the form was submitted, validate the input and create the attachments.
    if form.validate_on_submit():

        # Build a dictionary that maps image filenames to captions.
        # There will be one dictionary entry per selected item in the form.
        filename_caption_pairs = construct_filename_caption_dictionary_list(
            form)

        # Check that the user selected at least one image, then proceed to
        # make requests to the Classroom API.
        if len(filename_caption_pairs) > 0:
            return create_attachments(filename_caption_pairs)
        else:
            return flask.render_template(
                "create-attachment.html",
                message="You didn't select any images.",
                form=form,
                var_names=var_names)

    return flask.render_template(
        "attachment-options.html",
        message=("You've reached the attachment options page. "
                "Select one or more images and click 'Create Attachment'."),
        form=form,
        var_names=var_names,
    )

इससे "अटैचमेंट बनाएं" पेज बनता है, जो इस तरह दिखता है:

कॉन्टेंट चुनने के लिए Python का उदाहरण

शिक्षक, एक से ज़्यादा इमेज चुन सकता है. create_attachments तरीके में, शिक्षक की चुनी गई हर इमेज के लिए एक अटैचमेंट बनाएं.

अटैचमेंट बनाने के अनुरोध भेजना

अब आपको पता है कि शिक्षक किन कॉन्टेंट को अटैच करना चाहेगा. इसलिए, हमारे असाइनमेंट में अटैचमेंट बनाने के लिए, Classroom API को अनुरोध भेजें. Classroom API से जवाब मिलने के बाद, अटैचमेंट की जानकारी अपने डेटाबेस में सेव करें.

शुरुआत में, Classroom सेवा का इंस्टेंस पाएं:

Python

दिए गए उदाहरण में, यह webapp/attachment_routes.py फ़ाइल में है.

def create_attachments(filename_caption_pairs):
    """
    Create attachments and show an acknowledgement page.

    Args:
        filename_caption_pairs: A dictionary that maps image filenames to
            captions.
    """
    # Get the Google Classroom service.
    classroom_service = googleapiclient.discovery.build(
        serviceName="classroom",
        version="v1",
        credentials=credentials)

courses.courseWork.addOnAttachments एंडपॉइंट को CREATE अनुरोध भेजें. शिक्षक की चुनी गई हर इमेज के लिए, सबसे पहले एक AddOnAttachment ऑब्जेक्ट बनाएं:

Python

दिए गए उदाहरण में, यह create_attachments तरीके का हिस्सा है.

# Create a new attachment for each image that was selected.
attachment_count = 0
for key, value in filename_caption_pairs.items():
    attachment_count += 1

    # Create a dictionary with values for the AddOnAttachment object fields.
    attachment = {
        # Specifies the route for a teacher user.
        "teacherViewUri": {
            "uri":
                flask.url_for(
                    "load_content_attachment", _scheme='https', _external=True),
        },
        # Specifies the route for a student user.
        "studentViewUri": {
            "uri":
                flask.url_for(
                    "load_content_attachment", _scheme='https', _external=True)
        },
        # The title of the attachment.
        "title": f"Attachment {attachment_count}",
    }

हर अटैचमेंट के लिए, कम से कम teacherViewUri, studentViewUri, और title फ़ील्ड की जानकारी देना ज़रूरी है. teacherViewUri और studentViewUri, उन यूआरएल को दिखाते हैं जो उपयोगकर्ता के टाइप के हिसाब से, अटैचमेंट खोलने पर लोड होते हैं.

अनुरोध के मुख्य हिस्से में, AddOnAttachment ऑब्जेक्ट को सही addOnAttachments एंडपॉइंट पर भेजें. हर अनुरोध के साथ, courseId, itemId, itemType, और addOnToken आइडेंटिफ़ायर की जानकारी दें.

Python

दिए गए उदाहरण में, यह create_attachments तरीके का हिस्सा है.

# Use the itemType to determine which stream item type the teacher created
match flask.session["itemType"]:
    case "announcements":
        parent = classroom_service.courses().announcements()
    case "courseWorkMaterials":
        parent = classroom_service.courses().courseWorkMaterials()
    case _:
        parent = classroom_service.courses().courseWork()

# Issue a request to create the attachment.
resp = parent.addOnAttachments().create(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    addOnToken=flask.session["addOnToken"],
    body=attachment).execute()

अपने स्थानीय डेटाबेस में इस अटैचमेंट के लिए एक एंट्री बनाएं, ताकि बाद में सही कॉन्टेंट लोड किया जा सके. Classroom, अटैचमेंट बनाने के अनुरोध के जवाब में, यूनीक id वैल्यू दिखाता है. इसलिए, इसे अपने डेटाबेस में प्राइमरी की के तौर पर इस्तेमाल करें. यह भी ध्यान रखें कि Classroom, Teacher View और Student View खोलते समय, attachmentId क्वेरी पैरामीटर पास करता है:

Python

दिए गए उदाहरण में, यह create_attachments तरीके का हिस्सा है.

# Store the value by id.
new_attachment = Attachment(
    # The new attachment's unique ID, returned in the CREATE response.
    attachment_id=resp.get("id"),
    image_filename=key,
    image_caption=value)
db.session.add(new_attachment)
db.session.commit()

इस चरण पर, उपयोगकर्ता को पुष्टि करने वाले पेज पर ले जाने पर विचार करें. इससे उन्हें पता चलेगा कि उन्होंने अटैचमेंट बना लिए हैं.

अपने ऐड-ऑन से अटैचमेंट की अनुमति देना

अब Google Workspace Marketplace एसडीके टूल के ऐप्लिकेशन कॉन्फ़िगरेशन पेज में, 'अनुमति वाले अटैचमेंट यूआरआई प्रीफ़िक्स' फ़ील्ड में सही पते जोड़ने का सही समय है. आपका ऐड-ऑन, इस पेज पर मौजूद यूआरआई प्रीफ़िक्स में से सिर्फ़ एक का इस्तेमाल करके अटैचमेंट बना सकता है. यह सुरक्षा से जुड़ा मेज़रमेंट है, ताकि मैन-इन-द-मिडल हमलों की संभावना को कम किया जा सके.

सबसे आसान तरीका है कि इस फ़ील्ड में अपना टॉप-लेवल डोमेन डालें. जैसे, https://example.com. https://localhost:<your port number>/ अगर वेब सर्वर के तौर पर, अपने लोकल मशीन का इस्तेमाल किया जा रहा है, तो काम करेगा.

Teacher View और Student View के लिए रास्ते जोड़ना

Google Classroom के ऐड-ऑन को चार iframe में लोड किया जा सकता है. अब तक आपने सिर्फ़ ऐसे रास्ते बनाए हैं जो अटैचमेंट डिस्कवरी व्यू iframe को उपलब्ध कराते हैं. इसके बाद, Teacher View और Student View iframe को उपलब्ध कराने के लिए रास्ते जोड़ें.

Teacher View iframe, छात्र-छात्राओं के अनुभव की झलक दिखाने के लिए ज़रूरी है. हालांकि, इसमें अतिरिक्त जानकारी या बदलाव करने की सुविधाएं भी शामिल की जा सकती हैं.

Student View वह पेज है जो हर छात्र या छात्रा को, ऐड-ऑन अटैचमेंट खोलने पर दिखता है.

इस चरण के लिए, एक /load-content-attachment रूट बनाएं. यह Teacher View और Student View, दोनों को उपलब्ध कराता है. पेज लोड होने पर, यह पता लगाने के लिए Classroom API के तरीकों का इस्तेमाल करें कि उपयोगकर्ता शिक्षक है या छात्र/छात्रा.

Python

दिए गए उदाहरण में, यह webapp/attachment_routes.py फ़ाइल में है.

@app.route("/load-content-attachment")
def load_content_attachment():
    """
    Load the attachment for the user's role."""

    # Since this is a landing page for the Teacher and Student View iframes, we
    # need to preserve the incoming query parameters.
    if flask.request.args.get("itemId"):
        flask.session["itemId"] = flask.request.args.get("itemId")
    if flask.request.args.get("itemType"):
        flask.session["itemType"] = flask.request.args.get("itemType")
    if flask.request.args.get("courseId"):
        flask.session["courseId"] = flask.request.args.get("courseId")
    if flask.request.args.get("attachmentId"):
        flask.session["attachmentId"] = flask.request.args.get("attachmentId")

ध्यान रखें कि इस चरण पर, आपको उपयोगकर्ता को ऑथेंटिकेट भी करना चाहिए. आपको यहां login_hint क्वेरी पैरामीटर को भी मैनेज करना चाहिए. साथ ही, ज़रूरत पड़ने पर उपयोगकर्ता को अपने ऑथराइज़ेशन फ़्लो पर ले जाना चाहिए. इस फ़्लो के बारे में ज़्यादा जानकारी के लिए, पिछले लेखों में बताए गए लॉग इन करने के निर्देशों की जानकारी देखें.

इसके बाद, आइटम टाइप से मैच करने वाले getAddOnContext एंडपॉइंट को अनुरोध भेजें.

Python

दिए गए उदाहरण में, यह load_content_attachment तरीके का हिस्सा है.

# Create an instance of the Classroom service.
classroom_service = googleapiclient.discovery.build(
    serviceName="classroom"
    version="v1",
    credentials=credentials)

# Use the itemType to determine which stream item type the teacher created
match flask.session["itemType"]:
    case "announcements":
        parent = classroom_service.courses().announcements()
    case "courseWorkMaterials":
        parent = classroom_service.courses().courseWorkMaterials()
    case _:
        parent = classroom_service.courses().courseWork()

addon_context_response = parent.getAddOnContext(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"]).execute()

यह तरीका, क्लास में मौजूदा उपयोगकर्ता की भूमिका के बारे में जानकारी देता है. उपयोगकर्ता की भूमिका के हिसाब से, उसे दिखने वाले व्यू में बदलाव करें. जवाब के ऑब्जेक्ट में, studentContext या teacherContext फ़ील्ड में से सिर्फ़ एक में जानकारी होती है. इनकी जांच करके, यह तय करें कि उपयोगकर्ता को कैसे संबोधित करना है.

किसी भी मामले में, हमारे डेटाबेस से यह जानने के लिए कि कौनसे अटैचमेंट को वापस पाना है, attachmentId क्वेरी पैरामीटर वैल्यू का इस्तेमाल करें. Teacher View या Student View के यूआरआई खोलने पर, यह क्वेरी पैरामीटर उपलब्ध कराया जाता है.

Python

दिए गए उदाहरण में, यह load_content_attachment तरीके का हिस्सा है.

# Determine which view we are in by testing the returned context type.
user_context = "student" if addon_context_response.get(
    "studentContext") else "teacher"

# Look up the attachment in the database.
attachment = Attachment.query.get(flask.session["attachmentId"])

# Set the text for the next page depending on the user's role.
message_str = f"I see that you're a {user_context}! "
message_str += (
    f"I've loaded the attachment with ID {attachment.attachment_id}. "
    if user_context == "teacher" else
    "Please enjoy this image of a famous landmark!")

# Show the content with the customized message text.
return flask.render_template(
    "show-content-attachment.html",
    message=message_str,
    image_filename=attachment.image_filename,
    image_caption=attachment.image_caption,
    responses=response_strings)

ऐड-ऑन को टेस्ट करना

अटैचमेंट बनाने की सुविधा को टेस्ट करने के लिए, यह तरीका अपनाएं:

  • [Google Classroom] में, शिक्षक के तौर पर टेस्ट करने वाले किसी उपयोगकर्ता के तौर पर साइन इन करें.
  • क्लासवर्क टैब पर जाएं और नया असाइनमेंट बनाएं.
  • टेक्स्ट एरिया के नीचे मौजूद ऐड-ऑन बटन पर क्लिक करें. इसके बाद, अपना ऐड-ऑन चुनें. iframe खुलता है और ऐड-ऑन, अटैचमेंट सेटअप यूआरआई लोड करता है. यह यूआरआई, Google Workspace Marketplace एसडीके टूल के ऐप्लिकेशन कॉन्फ़िगरेशन पेज में तय किया गया है.
  • असाइनमेंट में अटैच करने के लिए, कोई कॉन्टेंट चुनें.
  • अटैचमेंट बनाने की प्रोसेस पूरी होने के बाद, iframe बंद करें.

आपको Google Classroom में, असाइनमेंट बनाने के यूआई में अटैचमेंट कार्ड दिखना चाहिए. Teacher View iframe खोलने के लिए, कार्ड पर क्लिक करें और पुष्टि करें कि सही अटैचमेंट दिख रहा है. असाइन करें बटन पर क्लिक करें.

छात्र-छात्राओं के अनुभव को टेस्ट करने के लिए, यह तरीका अपनाएं:

  • इसके बाद, Classroom में छात्र-छात्रा के तौर पर टेस्ट करने वाले किसी उपयोगकर्ता के तौर पर साइन इन करें. यह उपयोगकर्ता, शिक्षक के तौर पर टेस्ट करने वाले उपयोगकर्ता की क्लास में ही होना चाहिए.
  • क्लासवर्क टैब में, टेस्ट असाइनमेंट ढूंढें.
  • असाइनमेंट को बड़ा करें और Student View iframe खोलने के लिए, अटैचमेंट कार्ड पर क्लिक करें.

पुष्टि करें कि छात्र-छात्रा के लिए सही अटैचमेंट दिख रहा है.

बधाई हो! अब अगले चरण पर जाएं. इसमें, गतिविधि-टाइप अटैचमेंट बनाने के बारे में बताया गया है.