सुरक्षित, क्रॉस-डिवाइस और रिवर्सेबल क्रियाओं के लिए आप App Intents कैसे डिज़ाइन करते हैं?

1. परिदृश्य, लक्ष्य और सीमाएँ

एक सहयोग ऐप में प्रोजेक्ट्स, टिप्पणियाँ (comments) और कार्य (tasks) शामिल होते हैं। एक उपयोगकर्ता Siri, Spotlight, Shortcuts या Apple Intelligence के माध्यम से "कार्य पूरा करें", "प्रोजेक्ट साझा करें" या "टिप्पणी हटाएं" को इनवोक कर सकता है। प्रत्येक एंट्री पॉइंट को समान ऑथराइजेशन और परिणाम बनाए रखना चाहिए, और कार्य को किसी अन्य डिवाइस पर फिर से शुरू करने योग्य होना चाहिए।

पहले सीमा निर्धारित करें: App Intents क्रियाओं और एंटिटीज़ के लिए खोजे जा सकने वाले (discoverable) इंटरफेस हैं। उन्हें मौजूदा सर्वर ऑथराइजेशन, ऑडिट या ट्रांजेक्शन को बायपास नहीं करना चाहिए। सिस्टम सुझाव पहुँच बढ़ाते हैं लेकिन वे किसी इनवोकेशन को विश्वसनीय नहीं बनाते; प्रत्येक इंटेंट को एक सार्वजनिक कॉल सतह (public call surface) मानें।

2. App Intents का उत्पाद मूल्य

Apple का AppIntent प्रोटोकॉल ऐप क्रियाओं को Siri, Spotlight, Shortcuts और Apple Intelligence के लिए खोजे जाने योग्य बनाता है। जून 2026 App Intents अपडेट ऐप स्कीमा, SyncableEntity के माध्यम से स्थिर क्रॉस-डिवाइस एंटिटी पहचान, OwnershipProvidingEntity के माध्यम से संवेदनशील या विनाशकारी क्रियाओं के लिए स्वामित्व पुष्टिकरण, और अन्य ऐप्स द्वारा पैरामीटर के रूप में आपूर्ति की गई सामग्री प्राप्त करने के लिए IntentFile का भी वर्णन करते हैं।

ये क्षमताएँ खोज और सिमेंटिक इंटरऑपरेबिलिटी को हल करती हैं। वे व्यावसायिक ऑथराइजेशन, विरोध (conflict) समाधान, या अनडू (undo) नीति तय नहीं करती हैं। "उपयोगकर्ता क्या चाहता है", "क्या सिस्टम इसे सुरक्षित रूप से निष्पादित कर सकता है", और "उपयोगकर्ता विफलता से कैसे उबरता है" को अलग रखें।

3. क्रियाओं और एंटिटीज़ को मॉडल करें

प्रत्येक इंटेंट के लिए इनपुट, दृश्यता (visibility), पूर्वापेक्षाएँ (preconditions), परिणाम और साइड इफ़ेक्ट्स को परिभाषित करें। एक डिस्प्ले नाम बदल सकता है, लेकिन व्यावसायिक ID स्थिर, सत्यापन योग्य और वर्तमान उपयोगकर्ता तथा टेनेंट से बंधी होनी चाहिए। क्रॉस-डिवाइस पहचान के रूप में सूची स्थिति (list position), शीर्षक या स्थानीय डेटाबेस की (key) का उपयोग न करें।

struct CompleteTaskIntent: AppIntent {
    static var title: LocalizedStringResource = "Complete task"
    @Parameter(title: "Task")
    var task: TaskEntity

    func perform() async throws -> some IntentResult {
        try await TaskService.complete(taskID: task.id)
        return .result()
    }
}

यदि एंटिटी रिज़ॉल्यूशन विफल हो जाता है, अनुमतियाँ बदल जाती हैं, या संस्करण असंगत हैं, तो एक समझने योग्य विकल्प या साइन-इन पथ लौटाएँ। कभी भी किसी मिलते-जुलते प्रोजेक्ट का अनुमान लगाकर उसे निष्पादित न करें।

4. स्थिर क्रॉस-डिवाइस पहचान डिज़ाइन करें

यदि कोई कार्य कई डिवाइसेज़ पर जारी रह सकता है, तो उसकी एंटिटी को स्थिर पहचान सिमेंटिक्स प्रदर्शित करने चाहिए, और सर्वर को यह गारंटी देनी चाहिए कि वही एंटिटी ID प्रत्येक डिवाइस पर समान संसाधन को संदर्भित करती है। सिंक लेयर अभी भी विलोपन (deletion), संग्रह (archiving), टेनेंट स्थानांतरण और पुराने ऑफ़लाइन कैश को संभालती है; रिज़ॉल्यूशन यह पुन: जाँचता है कि वर्तमान उपयोगकर्ता संसाधन तक पहुँच सकता है या नहीं।

SyncableEntity को सिंक्रोनाइज़ेशन डेटाबेस न मानें। यह व्यक्त करता है कि पहचान सभी डिवाइसेज़ पर स्थिर रह सकती है; डेटा सिंक्रोनाइज़ेशन, विरोध समाधान और अनडू बैकएंड की ज़िम्मेदारियाँ बनी रहती हैं। विलय (merges) या माइग्रेशन के दौरान उपनाम मैपिंग (alias mappings) और ऑडिट रिकॉर्ड बनाए रखें ताकि कोई पुराना Shortcut गलत एंटिटी को लक्षित न कर सके।

5. संवेदनशील क्रियाओं और स्वामित्व की पुष्टि करें

हटाना, सार्वजनिक रूप से साझा करना, या एक्सेस स्थानांतरित करना यह पुष्टि करनी चाहिए कि उपयोगकर्ता एंटिटी का स्वामी है या उसके पास आवश्यक ऑपरेशन अनुमति है। स्वामित्व व्यक्त करने के लिए OwnershipProvidingEntity का उपयोग करें और पुष्टिकरण में ऑब्जेक्ट, प्रभाव और प्रतिवर्तीता (reversibility) को स्पष्ट करें। पुराने पुष्टिकरण का पुन: उपयोग करने के बजाय पुष्टिकरण को वर्तमान अनुरोध, उपयोगकर्ता और संसाधन संस्करण से बाँधें।

टीम के स्वामित्व वाली या सार्वजनिक एंटिटीज़ के लिए, सर्वर को स्वामित्व निर्णय लौटाना होगा; स्थानीय कैश पर्याप्त नहीं है। "दोबारा न पूछें" प्राथमिकताओं को सीमित रखें, और उच्च जोखिम वाली क्रियाओं के लिए पुष्टिकरण और ऑडिट बनाए रखें।

6. ऑथराइजेशन, आइडम्पोटेंसी और साइड इफ़ेक्ट्स

सिस्टम किसी इंटेंट का पुनः प्रयास (retry) कर सकता है, और एक Shortcut को दो बार चलाया जा सकता है। प्रत्येक स्थिति बदलने वाले (state-changing) इंटेंट में एक आइडम्पोटेंसी की (idempotency key) और संसाधन संस्करण होना चाहिए। ऑथराइजेशन के बाद, सर्वर एक सशर्त अपडेट (conditional update) निष्पादित करता है और डुप्लिकेट अनुरोध के लिए समान व्यावसायिक परिणाम लौटाता है। केवल-पढ़ने के लिए (read-only) क्रियाएं तेज़ हो सकती हैं, लेकिन फिर भी दृश्यता लागू करती हैं।

प्राकृतिक-भाषा पैरामीटर्स में अनुमति को एन्कोड न करें। सत्र, टेनेंट, एंटिटी स्वामित्व और वर्तमान संस्करण से पुनः ऑथराइज़ करें, और एंट्री पॉइंट (Siri, Spotlight, Shortcuts, या ऐप), कॉलर डिवाइस और परिणाम रिकॉर्ड करें। प्रतिक्रिया में समाप्त हो चुके लॉगिन (expired login), प्रतिबंधित एक्सेस (forbidden access), परिवर्तित एंटिटी और अस्थायी सेवा विफलता के बीच अंतर करें।

7. खोज, अवलोकन क्षमता (observability) और रिकवरी

प्रत्येक आंतरिक API को उजागर करने के बजाय उपयोगकर्ता मूल्य के आधार पर ऐप स्कीमा और खोजे जा सकने वाले कार्यों का चयन करें। प्रत्येक इंटेंट के लिए रिज़ॉल्यूशन सफलता, ऑथराइजेशन अस्वीकृति, पुष्टिकरण परित्याग (confirmation abandonment), डुप्लिकेट निष्पादन, क्रॉस-डिवाइस रिकवरी और पूर्णता दर को मापें। एंट्री पॉइंट्स की तुलना केवल इनवोकेशन संख्या से नहीं, बल्कि कन्वर्जन द्वारा करें।

निष्पादन से पहले एक सारांश और बाद में अनडू पथ के साथ परिणाम दिखाएं। नेटवर्क रुकावट पर, एक पुनः प्रयास योग्य अनुरोध स्थिति बनाए रखें लेकिन पृष्ठभूमि में किसी विनाशकारी क्रिया को अनिश्चित काल तक कभी भी रीप्ले न करें। यदि एंटिटी हटा दी जाती है या उसका संस्करण विरोध में है, तो एक ऑडिट इवेंट बनाए रखते हुए विकल्प और मानवीय-हैंडलिंग पथ लौटाएँ।

8. रूब्रिक और अनुवर्ती प्रश्न

अनिवार्य रूप से समझाना आवश्यक है

• App Intents को सार्वजनिक उत्पाद इंटरफेस के रूप में समझें, जिन्हें अभी भी सर्वर ऑथराइजेशन, ऑडिट, आइडम्पोटेंसी और संस्करण जाँच की आवश्यकता होती है।
• स्थिर एंटिटी पहचान को वास्तविक डेटा सिंक्रोनाइज़ेशन से अलग करें, जिसमें विलोपन, माइग्रेशन, ऑफ़लाइन स्थिति और विरोध शामिल हैं।
• संवेदनशील क्रियाओं के लिए स्वामित्व पुष्टिकरण, सीमित दायरे वाली पुष्टिकरण-छोड़ने की प्राथमिकताएं, अनडू और विफलता रिकवरी डिज़ाइन करें।

अनुवर्ती प्रश्न

• एक उपयोगकर्ता फ़ोन पर विलोपन की पुष्टि करता है, फिर टैबलेट पर एक ऑफ़लाइन Shortcut इसे फिर से चलाता है। सर्वर एक सुसंगत परिणाम की गारंटी कैसे देता है?
• एक साझा टीम प्रोजेक्ट का कोई एकल स्वामी नहीं है। अनुमति हस्तांतरण की पुष्टि कौन कर सकता है?
• आप यह कैसे तय करते हैं कि कोई इंटेंट शोरगुल वाली, कम मूल्य की क्रियाएं जोड़ने के बजाय सिस्टम सुझावों के योग्य है?

स्कोरिंग गाइड

एक उत्कृष्ट उत्तर खोज, पहचान, ऑथराइजेशन, पुष्टिकरण, आइडम्पोटेंसी और रिकवरी को एक उत्पाद श्रृंखला में जोड़ता है: सिस्टम एंट्री पॉइंट्स इंटेंट व्यक्त करते हैं, सर्वर अंतिम निर्णय लेता है, और उपयोगकर्ता प्रभाव को समझ सकता है तथा विफलता के बाद जारी रख सकता है।