تخزين البيانات الخاصة بالتطبيقات

مجلد بيانات التطبيق هو مجلد مخفي خاص يمكن لتطبيقك استخدامه لتخزين البيانات الخاصة بالتطبيق، مثل ملفات الإعدادات. يتم إنشاء مجلد data الخاص بالتطبيق تلقائيًا عند محاولة إنشاء ملف فيه. استخدِم هذا المجلد لتخزين أي ملفات لا يجب أن يتفاعل معها المستخدم مباشرةً. لا يمكن الوصول إلى هذا المجلد إلا من خلال تطبيقك، ويتم إخفاء محتوياته عن المستخدم وعن تطبيقات Google Drive الأخرى.

يتم حذف مجلد بيانات التطبيق عندما يزيل مستخدم تطبيقك من "ملفاتي". يمكن للمستخدمين أيضًا حذف مجلد بيانات تطبيقك يدويًا.

نطاق مجلد بيانات التطبيق

قبل أن تتمكّن من الوصول إلى مجلد بيانات التطبيق، يجب طلب الوصول إلى نطاق https://www.googleapis.com/auth/drive.appdata غير الحسّاس. للحصول على مزيد من المعلومات عن النطاقات وكيفية طلب الوصول إليها، يُرجى الاطّلاع على مقالة اختيار نطاقات Google Drive API. لمزيد من المعلومات عن نطاقات OAuth 2.0 المحدّدة، يُرجى الاطّلاع على نطاقات OAuth 2.0 لواجهات Google API.

أوجه الاختلاف بين مجلد بيانات التطبيق والمجلدات الاحتياطية في Drive

يكون مجلد بيانات التطبيق منفصلاً عن مجلد ملفاتك الاحتياطية في Drive.

مجلد بيانات التطبيق هو مجلد إعدادات يتم إنشاؤه لكل تطبيق تابع لجهة خارجية، ويمكن لكل تطبيق تابع لجهة خارجية تخزين البيانات فيه. لا يمكن الوصول إلى البيانات إلا من خلال التطبيق الذي أنشأها في appDataFolder. لا يمكن الوصول إلى الfolder باستخدام واجهة مستخدم Drive.

مجلد الاحتفاظ بنسخة احتياطية في Drive هو مجلد محجوز يُخزِّن فيه Drive النُسخ الاحتياطية للجهاز، وهو مرئي في واجهة مستخدم Drive.

القيود المفروضة على مجلد بيانات التطبيق

يتم فرض القيود التالية عند العمل مع ملف ملف بيانات التطبيق:

• لا يمكنك مشاركة الملفات أو المجلدات داخل مجلد بيانات التطبيق. يؤدي محاولة إجراء ذلك إلى ظهور خطأ notSupportedForAppDataFolderFiles مع رسالة الخطأ التالية: "الطريقة غير متوافقة مع الملفات ضمن مجلّد Application Data".

• لا يمكنك نقل الملفات في appDataFolder بين مواقع التخزين (المساحات). تؤدي محاولة إجراء ذلك إلى توليد خطأ notSupportedForAppDataFolderFiles مع ظهور رسالة الخطأ التالية: "الطريقة غير متوافقة مع الملفات ضمن مجلد "بيانات التطبيق". لمزيد من المعلومات، يمكنك الاطّلاع على ملف المؤسسة.

• لا يمكنك نقل الملفات أو المجلدات إلى المهملات داخل مجلد بيانات التطبيق. تؤدي محاولة إجراء ذلك إلى ظهور خطأ notSupportedForAppDataFolderFiles مع رسالة الخطأ التالية: "لا يمكن نقل الملفات ضمن مجلد "بيانات التطبيق" إلى المهملات".

إنشاء ملف في مجلد بيانات التطبيق

لإنشاء ملف في مجلد بيانات التطبيق، حدِّد appDataFolder في سمة parents للملف واستخدِم الأسلوب files.create لإنشاء الملف في المجلد.

يوضّح نموذج الرمز البرمجي التالي كيفية إدراج ملف في مجلد باستخدام مكتبة العميل وأمر curl.

ملاحظة: إذا كنت تستخدِم الإصدار 2 من Drive API الأقدم، يمكنك العثور على نماذج الرموز البرمجية في GitHub. تعرَّف على كيفية نقل البيانات إلى الإصدار 3 من Drive API.

Java

drive/snippets/drive_v3/src/main/java/UploadAppData.java

عرض على GitHub

import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.FileContent;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.drive.Drive;
import com.google.api.services.drive.DriveScopes;
import com.google.api.services.drive.model.File;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.Arrays;
import java.util.Collections;

/**
 * Class to demonstrate use-case of create file in the application data folder.
 */
public class UploadAppData {

  /**
   * Creates a file in the application data folder.
   *
   * @return Created file's Id.
   */
  public static String uploadAppData() throws IOException {
        /*Load pre-authorized user credentials from the environment.
        TODO(developer) - See https://developers.google.com/identity for
        guides on implementing OAuth2 for your application.*/
    GoogleCredentials credentials = null;
    try {
      credentials = GoogleCredentials.getApplicationDefault()
          .createScoped(Arrays.asList(DriveScopes.DRIVE_APPDATA));
    } catch (IOException e) {
      e.printStackTrace();
    }
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Build a new authorized API client service.
    Drive service = new Drive.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Drive samples")
        .build();
    try {
      // File's metadata.
      File fileMetadata = new File();
      fileMetadata.setName("config.json");
      fileMetadata.setParents(Collections.singletonList("appDataFolder"));
      java.io.File filePath = new java.io.File("files/config.json");
      FileContent mediaContent = new FileContent("application/json", filePath);
      File file = service.files().create(fileMetadata, mediaContent)
          .setFields("id")
          .execute();
      System.out.println("File ID: " + file.getId());
      return file.getId();
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      System.err.println("Unable to create file: " + e.getDetails());
      throw e;
    }
  }

}

Python

drive/snippets/drive-v3/app_data_snippet/upload_appdata.py

عرض على GitHub

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from googleapiclient.http import MediaFileUpload


def upload_appdata():
  """Insert a file in the application data folder and prints file Id.
  Returns : ID's of the inserted files

  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()

  try:
    # call drive api client
    service = build("drive", "v3", credentials=creds)

    # pylint: disable=maybe-no-member
    file_metadata = {"name": "abc.txt", "parents": ["appDataFolder"]}
    media = MediaFileUpload("abc.txt", mimetype="text/txt", resumable=True)
    file = (
        service.files()
        .create(body=file_metadata, media_body=media, fields="id")
        .execute()
    )
    print(f'File ID: {file.get("id")}')

  except HttpError as error:
    print(f"An error occurred: {error}")
    file = None

  return file.get("id")


if __name__ == "__main__":
  upload_appdata()

Node.js

drive/snippets/drive_v3/appdata_snippets/upload_appdata.js

عرض على GitHub

/**
 * Insert a file in the application data folder and prints file Id
 * */
async function uploadAppdata() {
  // Get credentials and build service
  // TODO (developer) - Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');
  const fs = require('fs');

  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive.appdata',
  });
  const service = google.drive({version: 'v3', auth});
  const fileMetadata = {
    name: 'config.json',
    parents: ['appDataFolder'],
  };
  const media = {
    mimeType: 'application/json',
    body: fs.createReadStream('files/config.json'),
  };
  try {
    const file = await service.files.create({
      requestBody: fileMetadata,
      media: media,
      fields: 'id',
    });
    console.log('File Id:', file.data.id);
    return file.data.id;
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

PHP

drive/snippets/drive_v3/src/DriveUploadAppData.php

عرض على GitHub

use Google\Client;
use Google\Service\Drive;
function uploadAppData()
{
   try {
    $client = new Client();
    $client->useApplicationDefaultCredentials();
    $client->addScope(Drive::DRIVE);
    $client->addScope(Drive::DRIVE_APPDATA);
    $driveService = new Drive($client);
    $fileMetadata = new Drive\DriveFile(array(
        'name' => 'config.json',
        'parents' => array('appDataFolder')
    ));
    $content = file_get_contents('../files/config.json');
    $file = $driveService->files->create($fileMetadata, array(
        'data' => $content,
        'mimeType' => 'application/json',
        'uploadType' => 'multipart',
        'fields' => 'id'));
    printf("File ID: %s\n", $file->id);
    return $file->id;

   } catch(Exception $e) {
     echo "Error Message: ".$e;
   }  
}

NET.

drive/snippets/drive_v3/DriveV3Snippets/UploadAppData.cs

عرض على GitHub

using Google.Apis.Auth.OAuth2;
using Google.Apis.Drive.v3;
using Google.Apis.Services;

namespace DriveV3Snippets
{
    // Class of demonstrate the use of Drive upload app data. 
    public class UploadAppData
    {
        /// <summary>
        /// Insert a file in the application data folder and prints file Id.
        /// </summary>
        /// <param name="filePath">File path to upload.</param>
        /// <returns>ID's of the inserted files, null otherwise.</returns>
        public static string DriveUploadAppData(string filePath)
        {
            try
            {
                /* Load pre-authorized user credentials from the environment.
                 TODO(developer) - See https://developers.google.com/identity for
                 guides on implementing OAuth2 for your application. */
                GoogleCredential credential = GoogleCredential.GetApplicationDefault()
                    .CreateScoped(DriveService.Scope.DriveAppdata);

                // Create Drive API service.
                var service = new DriveService(new BaseClientService.Initializer
                {
                    HttpClientInitializer = credential,
                    ApplicationName = "Drive API Snippets"
                });
                var fileMetadata = new Google.Apis.Drive.v3.Data.File()
                {
                    Name = "config.json",
                    Parents = new List<string>()
                    {
                        "appDataFolder"
                    }
                };
                FilesResource.CreateMediaUpload request;
                using (var stream = new FileStream(filePath,
                           FileMode.Open))
                {
                    request = service.Files.Create(
                        fileMetadata, stream, "application/json");
                    request.Fields = "id";
                    request.Upload();
                }

                var file = request.ResponseBody;
                // Prints the file id.
                Console.WriteLine("File ID: " + file.Id);
                return file.Id;
            }
            catch (Exception e)
            {
                // TODO(developer) - handle error appropriately
                if (e is AggregateException)
                {
                    Console.WriteLine("Credential Not found");
                }
                else
                {
                    throw;
                }
            }
            return null;
        }
    }
}

curl

الطلب:

curl --request POST \
'https://content.googleapis.com/drive/v3/files' \
    -H 'authorization: Bearer ACCESS_TOKEN' \
    -H 'content-type: application/json' \
    -H 'x-origin: https://explorer.apis.google.com' \
    --data-raw '{"name": "config.json", "parents":["appDataFolder"]}'

استبدِل ACCESS_TOKEN برمز OAuth 2.0 الخاص بتطبيقك.

الردّ:

{
    "kind": "drive#file",
    "id": FILE_ID,
    "name": "config.json",
    "mimeType": "application/json"
}

لمزيد من المعلومات عن إنشاء ملفات في المجلدات، يُرجى الاطّلاع على مقالة إنشاء المجلدات وملؤها.

البحث عن الملفات في مجلد بيانات التطبيق

للبحث عن الملفات في مجلد بيانات التطبيق، اضبط الحقل spaces على appDataFolder واستخدِم الطريقة files.list.

يوضّح نموذج الرمز البرمجي التالي كيفية البحث عن الملفات في مجلد data الخاص بالتطبيق باستخدام مكتبة عملاء وأمر curl.

ملاحظة: إذا كنت تستخدِم الإصدار 2 من Drive API الأقدم، يمكنك العثور على نماذج الرموز البرمجية في GitHub. تعرَّف على كيفية نقل البيانات إلى الإصدار 3 من Drive API.

Java

drive/snippets/drive_v3/src/main/java/ListAppData.java

عرض على GitHub

import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.drive.Drive;
import com.google.api.services.drive.DriveScopes;
import com.google.api.services.drive.model.File;
import com.google.api.services.drive.model.FileList;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.Arrays;

/**
 * Class to demonstrate use-case of list 10 files in the application data folder.
 */
public class ListAppData {

  /**
   * list down files in the application data folder.
   *
   * @return list of 10 files.
   */
  public static FileList listAppData() throws IOException {
        /*Load pre-authorized user credentials from the environment.
        TODO(developer) - See https://developers.google.com/identity for
        guides on implementing OAuth2 for your application.*/
    GoogleCredentials credentials = null;
    try {
      credentials = GoogleCredentials.getApplicationDefault()
          .createScoped(Arrays.asList(DriveScopes.DRIVE_APPDATA));
    } catch (IOException e) {
      e.printStackTrace();
    }
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Build a new authorized API client service.
    Drive service = new Drive.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Drive samples")
        .build();
    try {
      FileList files = service.files().list()
          .setSpaces("appDataFolder")
          .setFields("nextPageToken, files(id, name)")
          .setPageSize(10)
          .execute();
      for (File file : files.getFiles()) {
        System.out.printf("Found file: %s (%s)\n",
            file.getName(), file.getId());
      }

      return files;
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      System.err.println("Unable to list files: " + e.getDetails());
      throw e;
    }
  }

}

Python

drive/snippets/drive-v3/app_data_snippet/list_appdata.py

عرض على GitHub

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def list_appdata():
  """List all files inserted in the application data folder
  prints file titles with Ids.
  Returns : List of items

  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()

  try:
    # call drive api client
    service = build("drive", "v3", credentials=creds)

    # pylint: disable=maybe-no-member
    response = (
        service.files()
        .list(
            spaces="appDataFolder",
            fields="nextPageToken, files(id, name)",
            pageSize=10,
        )
        .execute()
    )
    for file in response.get("files", []):
      # Process change
      print(f'Found file: {file.get("name")}, {file.get("id")}')

  except HttpError as error:
    print(f"An error occurred: {error}")
    response = None

  return response.get("files")


if __name__ == "__main__":
  list_appdata()

Node.js

drive/snippets/drive_v3/appdata_snippets/list_appdata.js

عرض على GitHub

/**
 * Copyright 2022 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * List all files inserted in the application data folder
 * */
async function listAppdata() {
  // Get credentials and build service
  // TODO (developer) - Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive.appdata',
  });
  const service = google.drive({version: 'v3', auth});
  try {
    const res = await service.files.list({
      spaces: 'appDataFolder',
      fields: 'nextPageToken, files(id, name)',
      pageSize: 100,
    });
    res.data.files.forEach(function(file) {
      console.log('Found file:', file.name, file.id);
    });
    return res.data.files;
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

module.exports = listAppdata;

PHP

drive/snippets/drive_v3/src/DriveListAppData.php

عرض على GitHub

use Google\Client;
use Google\Service\Drive;
function listAppData()
{
    try {
        $client = new Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Drive::DRIVE);
        $driveService = new Drive($client);
        $response = $driveService->files->listFiles(array(
            'spaces' => 'appDataFolder',
            'fields' => 'nextPageToken, files(id, name)',
            'pageSize' => 10
        ));
        foreach ($response->files as $file) {
            printf("Found file: %s (%s)", $file->name, $file->id);
        }
        return $response->files;

    }catch(Exception $e) {
        echo "Error Message: ".$e;
    }

}

NET.

drive/snippets/drive_v3/DriveV3Snippets/ListAppData.cs

عرض على GitHub

using Google.Apis.Auth.OAuth2;
using Google.Apis.Drive.v3;
using Google.Apis.Drive.v3.Data;
using Google.Apis.Services;

namespace DriveV3Snippets
{
    // Class to demonstrate use-case of Drive's list files in the application data folder.
    public class ListAppData
    {
        /// <summary>
        /// List down files in the application data folder.
        /// </summary>
        /// <returns>list of 10 files, null otherwise.</returns>
        public static FileList DriveListAppData()
        {
            try
            {
                /* Load pre-authorized user credentials from the environment.
                 TODO(developer) - See https://developers.google.com/identity for
                 guides on implementing OAuth2 for your application. */
                GoogleCredential credential = GoogleCredential.GetApplicationDefault()
                    .CreateScoped(DriveService.Scope.DriveAppdata);

                // Create Drive API service.
                var service = new DriveService(new BaseClientService.Initializer
                {
                    HttpClientInitializer = credential,
                    ApplicationName = "Drive API Snippets"
                });

                var request = service.Files.List();
                request.Spaces = "appDataFolder";
                request.Fields = "nextPageToken, files(id, name)";
                request.PageSize = 10;
                var result = request.Execute();
                foreach (var file in result.Files)
                {
                    // Prints the list of 10 file names.
                    Console.WriteLine("Found file: {0} ({1})", file.Name, file.Id);
                }
                return result;
            }
            catch (Exception e)
            {
                // TODO(developer) - handle error appropriately
                if (e is AggregateException)
                {
                    Console.WriteLine("Credential Not found");
                }
                else
                {
                    throw;
                }
            }
            return null;
        }
    }
}

curl

الطلب:

curl \
    -X GET \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    "https://www.googleapis.com/drive/v3/files?spaces=appDataFolder&fields=files(id,name,mimeType,size,modifiedTime)"

استبدِل ACCESS_TOKEN برمز OAuth 2.0 الخاص بتطبيقك.

الردّ:

{
    "files": [
        {
            "mimeType": "application/json",
            "size": "256",
            "id": FILE_ID,
            "name": "config.json",
            "modifiedTime": "2025-04-03T23:40:05.860Z"
        },
        {
            "mimeType": "text/plain",
            "size": "128",
            "id": FILE_ID,
            "name": "user_settings.txt",
            "modifiedTime": "2025-04-02T17:52:29.020Z"
        }
    ]
}

تنزيل الملفات من مجلد بيانات التطبيق

لتنزيل ملف من مجلد بيانات التطبيق، استخدِم الطريقة files.get مع مَعلمة عنوان URL alt=media ل retrieving the file contents in the response body. لمزيد من المعلومات وعرض عيّنات الرموز البرمجية، انتقِل إلى مقالة تنزيل محتوى ملف ملف برمجي.

يوضّح نموذج الرمز البرمجي التالي كيفية تنزيل الملفات في مجلد data الخاص بالتطبيق باستخدام الأمر curl. سيختلف نص الاستجابة حسب ما يتم حفظه.

curl

الطلب:

curl \
    -X GET \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    "https://www.googleapis.com/drive/v3/files/FILE_ID?alt=media"

غيِّر القيم في السلسلة على الشكل التالي:

• ACCESS_TOKEN: رمز OAuth 2.0 لتطبيقك.
• FILE_ID: رقم تعريف الملف الذي تريد تنزيله.