مقدمة: تطوير التطبيقات باستخدام واجهة برمجة التطبيقات Data Portability API
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتيح لك Data Portability API إنشاء تطبيقات تطلب الإذن من العميل لنقل نسخة من البيانات من خدمات Google إلى تطبيقك. ويسمح ذلك
بنقل البيانات وتسهيل تبديل الخدمات.
عليك أيضًا التأكّد من توفّر واجهة برمجة التطبيقات Data Portability API للمستخدمين في
موقعك الجغرافي. للحصول على قائمة بالبلدان والمناطق التي تتوفّر فيها هذه الميزة، يُرجى الاطّلاع على الأسئلة الشائعة في صفحة "مشاركة نسخة من بياناتك مع جهة خارجية".
سير عمل المطوّر
في ما يلي الخطوات التي يجب اتّباعها لإنشاء تطبيق يستخدم واجهة برمجة التطبيقات
Data Portability API.
تنفيذ مسار الموافقة على OAuth للمستخدم في هذا المثال، يمنح المستخدم
إذن الوصول إلى بيانات فيديوهات YouTube.
ينقر المستخدم على استيراد فيديوهات YouTube ويُسجّل الدخول إلى حسابه على Google.
يوجّه التطبيق المستخدم إلى عنوان URL لموافقة OAuth. يُرجى العِلم أنّ مثال عنوان URL
هذا مبسّط ولا يتضمّن بعض المَعلمات:
ينقر المستخدم على التالي في شاشة طلب موافقة OAuth، ويوافق على مشاركة
بياناته، ويمنح إذن الوصول إلى الحساب.
يختار المستخدم البيانات التي يريد مشاركتها والمدة التي يمكن للتطبيق فيها
الوصول إلى هذه البيانات (إذن بالوصول لمرة واحدة إلى بياناته أو إذن بالوصول بالاستناد إلى الوقت لمدة
30 أو 180 يومًا)، ثمّ ينقر على متابعة.
ملاحظة:
يمكن للمستخدم تجديد إذن وصولك إلى بياناته قبل انتهاء صلاحية رمز OAuth بمدة تصل إلى 90 يومًا.
لا يظهر زر التجديد إذا لم يكن لدى المستخدم نطاقات تنتهي صلاحيتها
خلال 90 يومًا.
ملاحظة: إذا أراد المستخدم التبديل بين إذن الوصول لمرة واحدة وإذن الوصول المستند إلى الوقت، عليه إكمال عملية الموافقة مرة أخرى بعد إلغاء الإذن الحالي. يمكنك إلغاء المنح باستخدام
resetAuthorization()، أو يمكن للمستخدم إلغاء المنح من صفحة "عمليات الربط".
تتم إعادة توجيه المستخدم إلى التطبيق.
يحصل المطوّر على رمز مميّز لبروتوكول OAuth للمستخدم.
يطلب تطبيقك InitiatePortabilityArchive(resources = ["myactivity.youtube"]) باستخدام رمز مميز لبروتوكول OAuth مرفق يحتوي على نطاق OAuth التالي:
يبدأ هذا الطلب عملية إنشاء أرشيف البيانات ويردّ بقيمة
معرّف الوظيفة وما إذا كان المستخدم قد منَح إذن وصول لمرة واحدة أو إذن وصول مستندًا إلى الوقت.
ملاحظة:
يعني الوصول لمرة واحدة عملية تصدير واحدة لكل نطاق. إذا منح المستخدم
نطاقات متعددة، يمكنك اختيار إنشاء مهام منفصلة لكلٍّ من
الموارد التي يوافق عليها الرمز المميّز.
يطلب تطبيقك GetPortabilityArchiveState(job_id) باستخدام رمز أمان OAuth
مرفق يحتوي على نطاق OAuth التالي:
يمكنك استدعاء هذه الطريقة عدة مرات لاسترداد حالة مهمة
الأرشفة. تُعرِض الطريقة حالة المهمة. إذا كانت الحالة هي COMPLETE،
يكون الأرشيف جاهزًا، ويتم توفير عناوين URL موقَّعة في Cloud Storage. يُرجى العِلم أنّه
يمكن أن يختلف الوقت المستغرَق لإكمال طلب الأرشفة من دقائق إلى
ساعات استنادًا إلى حجم البيانات.
نزِّل أرشيف البيانات باستخدام عناوين URL الموقَّعة.
إذا منح المستخدم إذن الوصول لمرة واحدة، يمكنك الاتصال بـ ResetAuthorization() باستخدام
رمز مميّز OAuth مرفق لإعادة ضبط الموارد المستنفدة وإزالة جميع موافقة
OAuth.
إذا منح المستخدم إذن الوصول المستند إلى الوقت، يمكنك تصدير الموارد كل 24
ساعة إلى أن تنتهي صلاحية الموافقة.
كيفية تفاعل المستخدمين مع تطبيق يستخدم واجهة برمجة التطبيقات Data Portability API
يوضِّح هذا المخطّط البياني كيفية تفاعل المستخدمين مع تطبيق مدمج مع واجهة برمجة التطبيقات
Data Portability API.
أولاً، يتم عرض خيار على المستخدم لاسترداد بياناته.
بعد ذلك، يسجّل المستخدم الدخول إلى حسابه على Google.
بعد ذلك، ينقر المستخدم على التالي عندما يُطلب منه مشاركة بياناته، ويُقرّ على أفهم عندما يُطلب منه قبول سياسة
الخصوصية.
بعد ذلك، تظهر للمستخدم شاشة طلب موافقة OAuth التي تُستخدَم للسماح
للتطبيق بالوصول إلى بياناته. تتطابق الخيارات هنا مع نطاقات OAuth
التي أعددتها. يختار المستخدم البيانات التي يريد مشاركتها والمدة التي
يمكن للتطبيق خلالها الوصول إلى هذه البيانات (إذن بالوصول لمرة واحدة إلى بياناته أو
إذن بالوصول بالاستناد إلى الوقت لمدة 30 أو 180 يومًا)، ثمّ ينقر على متابعة.
بعد السماح بالوصول، تبدأ عملية استيراد البيانات. استنادًا إلى حجم
البيانات، يمكن أن يستغرق اكتمال الطلب من عدة دقائق إلى عدة ساعات.
تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe Data Portability API allows developers to build applications that enable users to move a copy of their data from Google services to another application, facilitating service switching.\u003c/p\u003e\n"],["\u003cp\u003eBefore releasing an application using this API, developers must obtain approval from Google and ensure the API is available in the user's region.\u003c/p\u003e\n"],["\u003cp\u003eThe developer workflow involves implementing the OAuth consent flow, initiating the data archive creation, monitoring its status, downloading the archive using provided URLs, and finally resetting authorization.\u003c/p\u003e\n"],["\u003cp\u003eUsers interact with Data Portability API applications by initiating data retrieval, signing into their Google Account, granting necessary permissions, and waiting for the data import process to complete.\u003c/p\u003e\n"],["\u003cp\u003eData Portability API features are not accessible to users under 18 years of age, resulting in an error message if they attempt to use them.\u003c/p\u003e\n"]]],[],null,["# Introduction: Develop apps using the Data Portability API\n\nThe Data Portability API lets you build applications that request authorization from a\nuser to move a copy of data from Google services into your application. This\nenables data portability and facilitates switching services.\n\nIf you are looking for information on how users share data, see [Share a copy of\nyour data with a third party](https://support.google.com/accounts/answer/14452558).\n\nPrerequisites\n-------------\n\nBefore releasing your app, it must be [approved](/data-portability/user-guide/client-verification) by Google.\n\nYou should also verify that the Data Portability API is available to users in\nyour location. For a list of supported countries and regions, see\n[Common Questions](https://support.google.com/accounts/answer/14452558) on the \"Share a copy of your data with a third\nparty\" page.\n\nDeveloper workflow\n------------------\n\nThese are the steps you follow to create an application that uses the\nData Portability API.\n\n1. Implement the OAuth consent flow for the user. In this example, the user is\n providing access to YouTube video data.\n\n 1. The user clicks **Import YouTube Videos** and signs into their Google\n Account.\n\n 2. The app forwards the user to an OAuth consent URL. Note that this\n example URL is simplified and is missing some parameters:\n\n `https://accounts.google.com/o/oauth2/v2/auth?scope=https://www.googleapis.com/auth/dataportability.myactivity.youtube`\n 3. The user clicks **Next** on the OAuth consent screen, agrees to share\n their data, and provides account access.\n\n 4. The user selects what data to share and the amount of time the app can\n access that data (*one-time access* to their data or *time-based access* for\n 30 or 180 days), then clicks **Continue**.\n\n **Note**:\n Up to 90 days before your OAuth token expires, the user has the option\n of renewing your access to their data before your OAuth token expires.\n The renew button doesn't appear if the user doesn't have scopes expiring\n within 90 days.\n\n **Note** : If the user wants to switch between *one-time access* and\n *time-based access* they will need to go through the consent flow again\n after the existing grant has been revoked. You can revoke the grant with\n `resetAuthorization()`, or the user can revoke on their [connections\n page](http://myaccount.google.com/connections).\n 5. The user is redirected to the app.\n\n 6. The developer obtains an OAuth token for the user.\n\n2. Your app calls\n `InitiatePortabilityArchive(resources = [\"myactivity.youtube\"])` with\n an attached OAuth token that contains this OAuth scope:\n\n `https://www.googleapis.com/auth/dataportability.myactivity.youtube`\n\n This call starts the process of creating the data archive and responds with\n a job ID and whether the user granted one-time or time-based access.\n\n **Note** :\n One-time access means one export *per scope*. If the user grants\n multiple scopes, you may choose to create separate jobs for each of the\n resources authorized by the token.\n | **Tip:** You should initiate the portability archive within 24 hours of user authorization.\n3. Your app calls `GetPortabilityArchiveState(job_id)` with an attached OAuth\n token that contains this OAuth scope:\n\n `https://www.googleapis.com/auth/dataportability.myactivity.youtube`\n\n You can call this method multiple times to retrieve the status of the\n archive job. The method returns the job's state. If the state is `COMPLETE`,\n the archive is ready, and signed Cloud Storage URLs are provided. Note that\n the time it takes to complete the archive request can vary from minutes to\n hours depending on the size of the data.\n4. Download the data archive using the signed URLs.\n\n5. *If the user grants one-time access* , you call `ResetAuthorization()` with\n an attached OAuth token to reset exhausted resources and to remove all OAuth\n consents.\n\n6. *If the user grants time-based access*, you can export resources every 24\n hours until the consent expires.\n\nFor more information on using the Data Portability API methods, see\n[Call Data Portability API methods](/data-portability/user-guide/methods).\n\nHow users interact with a Data Portability API app\n--------------------------------------------------\n\nThis diagram shows how users interact with an app that's integrated with the\nData Portability API.\n\n1. First, the user is presented with an option to retrieve their data.\n\n2. Next, the user signs into their Google Account.\n\n3. Then, the user clicks **Next** when they're prompted to share their data,\n and they click **I understand** when they're prompted to accept the privacy\n policy.\n\n4. Then, the user is shown an OAuth consent screen that is used to allow the\n application to access their data. The options here match the OAuth scopes\n you configured. The user selects what data to share and the amount of time\n the app can access that data (*one-time access* to their data or\n *time-based access* for 30 or 180 days), then clicks **Continue**.\n\n5. After allowing access, the data import starts. Depending on the size of the\n data, the request can take several minutes to several hours to complete."]]
