ذخیره داده های خاص برنامه

پوشه داده‌های برنامه ، یک پوشه مخفی ویژه است که برنامه شما می‌تواند از آن برای ذخیره داده‌های خاص برنامه، مانند فایل‌های پیکربندی، استفاده کند. پوشه داده‌های برنامه به طور خودکار هنگام تلاش برای ایجاد فایلی در آن ایجاد می‌شود. از این پوشه برای ذخیره هر فایلی که کاربر نباید مستقیماً با آن تعامل داشته باشد استفاده کنید. این پوشه فقط توسط برنامه شما قابل دسترسی است و محتویات آن از کاربر و سایر برنامه‌های Google Drive پنهان است.

پوشه داده‌های برنامه زمانی حذف می‌شود که کاربر برنامه شما را از My Drive خود حذف نصب کند. کاربران همچنین می‌توانند پوشه داده‌های برنامه شما را به صورت دستی حذف کنند.

محدوده پوشه داده‌های برنامه

قبل از اینکه بتوانید به پوشه داده‌های برنامه دسترسی پیدا کنید، باید درخواست دسترسی به محدوده غیرحساس https://www.googleapis.com/auth/drive.appdata را بدهید. برای اطلاعات بیشتر در مورد محدوده‌ها و نحوه درخواست دسترسی به آنها، به «انتخاب محدوده‌های API گوگل درایو» مراجعه کنید. برای اطلاعات بیشتر در مورد محدوده‌های خاص OAuth 2.0، به «محدوده‌های OAuth 2.0 برای APIهای گوگل» مراجعه کنید.

تفاوت پوشه داده‌های برنامه با پوشه‌های پشتیبان‌گیری درایو

پوشه داده‌های برنامه از پوشه پشتیبان‌گیری Drive شما جدا است.

پوشه داده‌های برنامه، یک پوشه پیکربندی است که برای هر برنامه شخص ثالث ایجاد می‌شود و هر برنامه شخص ثالث می‌تواند داده‌ها را در آن ذخیره کند. فقط برنامه‌ای که داده‌ها را در پوشه appDataFolder ایجاد کرده است می‌تواند به آن دسترسی داشته باشد. دسترسی به این پوشه با استفاده از رابط کاربری (UI) درایو امکان‌پذیر نیست.

پوشه پشتیبان‌گیری درایو شما یک پوشه رزرو شده است که درایو پشتیبان‌گیری‌های دستگاه را در آن می‌نویسد و در رابط کاربری درایو قابل مشاهده است.

محدودیت‌های پوشه داده‌های برنامه

محدودیت‌های زیر هنگام کار با پوشه داده‌های برنامه اعمال می‌شوند:

  • شما نمی‌توانید فایل‌ها یا پوشه‌های داخل پوشه‌ی داده‌های برنامه را به اشتراک بگذارید. تلاش برای انجام این کار خطای notSupportedForAppDataFolderFiles با پیام خطای زیر ایجاد می‌کند: "روش برای فایل‌های داخل پوشه‌ی داده‌های برنامه پشتیبانی نمی‌شود."

  • شما نمی‌توانید فایل‌های موجود در پوشه appDataFolder را بین مکان‌های ذخیره‌سازی (فضاها) جابجا کنید. تلاش برای انجام این کار، خطای notSupportedForAppDataFolderFiles را با پیام خطای زیر ایجاد می‌کند: "روش برای فایل‌های درون پوشه Application Data پشتیبانی نمی‌شود." برای اطلاعات بیشتر، به سازماندهی فایل مراجعه کنید.

  • شما نمی‌توانید فایل‌ها یا پوشه‌های داخل پوشه‌ی داده‌های برنامه را به سطل زباله بیندازید. تلاش برای انجام این کار خطای notSupportedForAppDataFolderFiles با پیام خطای زیر ایجاد می‌کند: "فایل‌های داخل پوشه‌ی داده‌های برنامه قابل حذف نیستند."

یک فایل در پوشه داده‌های برنامه ایجاد کنید

برای ایجاد یک فایل در پوشه‌ی داده‌های برنامه، appDataFolder را در ویژگی parents فایل مشخص کنید و از متد files.create برای ایجاد فایل در پوشه استفاده کنید.

نمونه کد زیر نحوه درج یک فایل در یک پوشه با استفاده از یک کتابخانه کلاینت و دستور curl را نشان می‌دهد.

جاوا

‎drive/snippets/drive_v3/src/main/java/UploadAppData.java‎‏
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;
    }
  }

}

پایتون

‎drive/snippets/drive-v3/app_data_snippet/upload_appdata.py‎‏
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()

نود جی اس

‎drive/snippets/drive_v3/appdata_snippets/upload_appdata.js‎‏
import fs from 'node:fs';
import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Uploads a file to the application data folder.
 * @return {Promise<string>} The ID of the uploaded file.
 */
async function uploadAppdata() {
  // Authenticate with Google and get an authorized client.
  // TODO (developer): Use an appropriate auth mechanism for your app.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive.appdata',
  });

  // Create a new Drive API client (v3).
  const service = google.drive({version: 'v3', auth});

  // The metadata for the file to be uploaded.
  const fileMetadata = {
    name: 'config.json',
    parents: ['appDataFolder'],
  };

  // The media content to be uploaded.
  const media = {
    mimeType: 'application/json',
    body: fs.createReadStream('files/config.json'),
  };

  // Upload the file to the application data folder.
  const file = await service.files.create({
    requestBody: fileMetadata,
    media,
    fields: 'id',
  });

  // Print the ID of the uploaded file.
  console.log('File Id:', file.data.id);
  if (!file.data.id) {
    throw new Error('File ID not found.');
  }
  return file.data.id;
}

پی اچ پی

‎drive/snippets/drive_v3/src/DriveUploadAppData.php‎‏
<?php
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;
   }  
}

دات نت

‎drive/snippets/drive_v3/DriveV3Snippets/UploadAppData.cs‎‏
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 --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 استفاده کنید.

نمونه کد زیر نحوه جستجوی فایل‌ها در پوشه داده‌های برنامه را با استفاده از یک کتابخانه کلاینت و دستور curl نشان می‌دهد.

جاوا

‎drive/snippets/drive_v3/src/main/java/ListAppData.java‎‏
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;
    }
  }

}

پایتون

‎drive/snippets/drive-v3/app_data_snippet/list_appdata.py‎‏
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()

نود جی اس

‎drive/snippets/drive_v3/appdata_snippets/list_appdata.js‎‏
/**
 * 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.
 */


import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Lists all files in the application data folder.
 * @return {Promise<object[]>} A list of files.
 */
async function listAppdata() {
  // Authenticate with Google and get an authorized client.
  // TODO (developer): Use an appropriate auth mechanism for your app.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive.appdata',
  });

  // Create a new Drive API client (v3).
  const service = google.drive({version: 'v3', auth});

  // List the files in the application data folder.
  const result = await service.files.list({
    spaces: 'appDataFolder',
    fields: 'nextPageToken, files(id, name)',
    pageSize: 100,
  });

  // Print the name and ID of each file.
  (result.data.files ?? []).forEach((file) => {
    console.log('Found file:', file.name, file.id);
  });

  return result.data.files ?? [];
}

export {listAppdata};

پی اچ پی

‎drive/snippets/drive_v3/src/DriveListAppData.php‎‏
<?php
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;
    }

}

دات نت

‎drive/snippets/drive_v3/DriveV3Snippets/ListAppData.cs‎‏
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 \
    -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 به همراه پارامتر alt=media URL برای بازیابی محتوای فایل در بدنه پاسخ استفاده کنید. برای اطلاعات بیشتر و مشاهده نمونه‌های کد، به Download blob file content بروید.

نمونه کد زیر نحوه دانلود فایل‌های موجود در پوشه داده‌های برنامه را با استفاده از دستور 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 : شناسه فایلی که می‌خواهید دانلود کنید.