این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

از Discovery API استفاده کنید

این سند برای توسعه دهندگانی در نظر گرفته شده است که می خواهند کتابخانه های مشتری، افزونه های IDE و ابزارهای دیگر برای تعامل با Google API بنویسند. سرویس Google APIs Discovery به شما این امکان را می‌دهد تا با افشای ابرداده‌های قابل خواندن ماشینی در مورد سایر APIهای Google از طریق یک API ساده، همه موارد فوق را انجام دهید. این راهنما یک نمای کلی از هر بخش از سند Discovery و همچنین نکات مفیدی در مورد نحوه استفاده از سند ارائه می دهد.

همه تماس‌ها به API، درخواست‌های REST مبتنی بر JSON هستند که از SSL استفاده می‌کنند، به عبارت دیگر، URL‌ها با https شروع می‌شوند.

قالب سند کشف

این بخش یک نمای کلی از سند Discovery ارائه می دهد.

همه مثال‌های زیر از سند Discovery از سرویس Usage API استفاده می‌کنند. با اجرای این درخواست GET می‌توانید سند Discovery را برای سرویس Usage API بارگیری کنید:

GET https://serviceusage.googleapis.com/$discovery/rest?version=v1

قالب یک سند کشف شامل اطلاعاتی است که در شش دسته اصلی قرار می گیرند:

توضیحات اولیه API
اطلاعات احراز هویت برای API.
جزئیات منبع و طرحواره که داده های API را توصیف می کند.
جزئیات در مورد روش های API .
اطلاعات مربوط به هر ویژگی سفارشی پشتیبانی شده توسط API.
اسناد درون خطی که عناصر کلیدی API را توصیف می کند.

هر یک از این بخش های سند Discovery در زیر توضیح داده شده است.

توضیحات پایه API

سند Discovery شامل مجموعه ای از ویژگی های خاص API است. این ویژگی ها لزوماً به این ترتیب یا در همان بخش سند کشف ظاهر نمی شوند:

"id": "serviceusage:v1",
"canonicalName": "Service Usage",
"revision": "20240331",
"servicePath": "",
"baseUrl": "https://serviceusage.googleapis.com/",
"kind": "discovery#restDescription",
"description": "Enables services that service consumers want to use on Google Cloud Platform, lists the available or enabled services, or disables services that service consumers no longer use.",
"ownerDomain": "google.com",
"version_module": true,
"version": "v1",
"fullyEncodeReservedExpansion": true,
"name": "serviceusage",
"title": "Service Usage API",
"discoveryVersion": "v1",
"rootUrl": "https://serviceusage.googleapis.com/",
"protocol": "rest"

این ویژگی‌های سطح API شامل جزئیات مربوط به یک نسخه خاص از یک API، از جمله name ، version ، title و description . protocol همیشه مقدار ثابتی از rest دارد، زیرا سرویس کشف APIها فقط از روش‌های RESTful برای دسترسی به APIها پشتیبانی می‌کند.

قسمت servicePath پیشوند مسیر را برای این نسخه API خاص نشان می دهد.

احراز هویت

بخش auth حاوی جزئیاتی در مورد حوزه های تأیید OAuth 2.0 برای API است. برای کسب اطلاعات بیشتر در مورد نحوه استفاده از دامنه‌ها با OAuth 2.0، به استفاده از OAuth 2.0 برای دسترسی به Google API مراجعه کنید.

بخش auth شامل oauth2 تودرتو و بخش scopes است. بخش scopes یک نگاشت کلید/مقدار از مقدار scope تا جزئیات بیشتر در مورد محدوده است:

"auth": {
  "oauth2": {
    "scopes": {
      "https://www.googleapis.com/auth/cloud-platform": {
        "description": "See, edit, configure, and delete your Google Cloud data and see the email address for your Google Account."
      },
      "https://www.googleapis.com/auth/cloud-platform.read-only": {
        "description": "View your data across Google Cloud services and see the email address of your Google Account"
      },
      "https://www.googleapis.com/auth/service.management": {
        "description": "Manage your Google API service configuration"
      }
    }
  }
}

بخش auth فقط محدوده های یک API خاص را تعریف می کند. برای آشنایی با نحوه ارتباط این حوزه‌ها با یک روش API، به بخش روش‌ها در زیر مراجعه کنید.

منابع و طرحواره ها

عملیات یک API بر روی اشیاء داده ای به نام resources عمل می کند. سند Discovery بر اساس مفهوم منابع ساخته شده است. هر سند Discovery یک بخش resources سطح بالایی دارد که تمام منابع مرتبط با API را گروه بندی می کند. به عنوان مثال، سرویس Usage API دارای یک منبع services و یک منبع operations تحت resources سطح بالا است:

"resources": {
  "services": {
    // Methods associated with the services resource
  }
  "operations": {
    // Methods associated with the operations resource
  }
}

در داخل هر بخش منبع، روش های مرتبط با آن منبع وجود دارد. به عنوان مثال، سرویس Usage API دارای شش روش مرتبط با منبع services است: get , enable , disable , batchGet , batchEnable و list .

طرحواره ها به شما می گویند که منابع موجود در یک API چگونه هستند. هر سند Discovery یک بخش schemas سطح بالایی دارد که شامل یک جفت نام/مقدار از شناسه طرحواره برای شیء است. شناسه‌های طرحواره برای هر API منحصربه‌فرد هستند و برای شناسایی منحصربه‌فرد طرحواره در بخش methods سند کشف استفاده می‌شوند. به عنوان مثال، در اینجا تعدادی از طرحواره های موجود در سند سرویس Usage API Discovery آورده شده است:

"schemas": {
  "Method": {
    // JSON schema of the Method resource
  },
  "Authentication": {
    // JSON schema of the Authentication resource
  },
  "RubySettings": {
    // JSON schema of the RubySettings resource
  },
  "EnableServiceResponse": {
   // JSON schema of the EnableServiceResponse resource
  }
}

APIs Discovery Service از JSON Schema draft-03 برای نمایش طرحواره خود استفاده می کند. در زیر قطعه ای از طرحواره JSON برای منبع EnableServiceResponse به همراه GoogleApiServiceusagev1Service است که به آن ارجاع می دهد. در کنار این طرحواره ها، بخشی از یک پاسخ واقعی برای درخواست فعال کردن Pub/Sub API ( pubsub.googleapis.com ) وجود دارد.

طرحواره JSON منبع EnableServiceResponse : پاسخ واقعی برای فعال کردن یک سرویس:

"EnableServiceResponse": {
  "id": "EnableServiceResponse",
  "description": "Response message for the `EnableService` method. This response message is assigned to the `response` field of the returned Operation when that operation is done.",
  "properties": {
    "service": {
      "description": "The new state of the service after enabling.",
      "$ref": "GoogleApiServiceusageV1Service"
    }
  },
  "type": "object"
},
"GoogleApiServiceusageV1Service": {
  "description": "A service that is available for use by the consumer.",
  "properties": {
    "config": {
      "$ref": "GoogleApiServiceusageV1ServiceConfig",
      "description": "The service configuration of the available service. Some fields may be filtered out of the configuration in responses to the `ListServices` method. These fields are present only in responses to the `GetService` method."
    },
    "name": {
      "type": "string",
      "description": "The resource name of the consumer and service. A valid name would be: - projects/123/services/serviceusage.googleapis.com"
    },
    "state": {
      "enumDescriptions": [
        "The default value, which indicates that the enabled state of the service is unspecified or not meaningful. Currently, all consumers other than projects (such as folders and organizations) are always in this state.",
        "The service cannot be used by this consumer. It has either been explicitly disabled, or has never been enabled.",
        "The service has been explicitly enabled for use by this consumer."
      ],
      "description": "Whether or not the service has been enabled for use by the consumer.",
      "type": "string",
      "enum": [
        "STATE_UNSPECIFIED",
        "DISABLED",
        "ENABLED"
      ]
    },
    "parent": {
      "type": "string",
      "description": "The resource name of the consumer. A valid name would be: - projects/123"
    }
  },
  "id": "GoogleApiServiceusageV1Service",
  "type": "object"
}

"response": {
  "@type": "type.googleapis.com/google.api.serviceusage.v1.EnableServiceResponse",
  "service": {
    "name": "projects/232342569935/services/pubsub.googleapis.com",
    "config": {
      "name": "pubsub.googleapis.com",
      "title": "Cloud Pub/Sub API",
      "documentation": {
        "summary": "Provides reliable, many-to-many, asynchronous messaging between applications.\n"
      },
      "quota": {},
      "authentication": {},
      "usage": {
        "requirements": [
          "serviceusage.googleapis.com/tos/cloud"
        ]
      },
      "monitoring": {}
    },
    "state": "ENABLED",
    "parent": "projects/232342569935"
  }
}

فیلدهای پررنگ نگاشت بین طرحواره JSON و پاسخ واقعی را نشان می دهند.

همانطور که در این مثال نشان داده شده است، طرحواره ها می توانند ارجاعاتی به طرحواره های دیگر داشته باشند. اگر در حال ساختن یک کتابخانه کلاینت هستید، این می تواند به شما کمک کند تا به طور موثر اشیاء یک API را در کلاس های مدل داده خود مدل سازی کنید. در مثال EnableServiceResponse در بالا، ویژگی service ارجاع به طرحی با شناسه GoogleApiServiceusageV1Service است، طرحی دیگر در سند سرویس Usage API Discovery. می توانید ویژگی GoogleApiServiceusageV1Service در منبع EnableServiceResponse با مقدار طرحواره GoogleApiServiceusageV1Service جایگزین کنید (توجه داشته باشید که دستور $ref از مشخصات طرحواره JSON می آید).

روش‌ها همچنین ممکن است به طرح‌واره‌ها هنگام نشان دادن درخواست و پاسخ‌دهی خود ارجاع دهند. برای جزئیات بیشتر به بخش روش ها مراجعه کنید.

روش ها

هسته سند Discovery حول روش ها ساخته شده است. متدها عملیاتی هستند که می توان روی یک API انجام داد. بخش methods در بخش‌های مختلف سند Discovery، از جمله در سطح بالا (که ما روش‌های سطح API می‌نامیم) یا در سطح resources ، پیدا خواهید کرد.

"methods": {
  // API-level methods
}
"resources": {
  "resource1": {
    "methods": {
      // resource-level methods
    }
    "resources": {
      "nestedResource": {
        "methods": {
          // methods can even be found in nested-resources
        }
      }
    }
  }
}

در حالی که یک API می تواند متدهای سطح API داشته باشد، یک منبع باید دارای بخش methods باشد.

هر بخش methods یک نقشه کلید-مقدار از نام روش تا سایر جزئیات مربوط به آن روش است. مثال زیر سه روش get ، enable و disable مستند می کند:

"methods": {
  "get": { //details about the "get" method },
  "enable": { //details about the "enable" method },
  "disable": { //details about the "disable" method }
}

در نهایت، بخش هر روش به جزئیات خواص مختلف آن روش می‌پردازد. در اینجا یک مثال از روش enable آورده شده است:

"enable": {
  "path": "v1/{+name}:enable",
  "request": {
    "$ref": "EnableServiceRequest"
  },
  "parameterOrder": [
    "name"
  ],
  "id": "serviceusage.services.enable",
  "response": {
    "$ref": "Operation"
  },
  "description": "Enable a service so that it can be used with a project.",
  "httpMethod": "POST",
  "flatPath": "v1/{v1Id}/{v1Id1}/services/{servicesId}:enable",
  "scopes": [
    "https://www.googleapis.com/auth/cloud-platform",
    "https://www.googleapis.com/auth/service.management"
  ],
  "parameters": {
    "name": {
      "location": "path",
      "description": "Name of the consumer and service to enable the service on. The `EnableService` and `DisableService` methods currently only support projects. Enabling a service requires that the service is public or is shared with the user enabling the service. An example name would be: `projects/123/services/serviceusage.googleapis.com` where `123` is the project number.",
      "required": true,
      "type": "string",
      "pattern": "^[^/]+/[^/]+/services/[^/]+$"
    }
  }
},

این بخش شامل جزئیات کلی روش مانند ID منحصر به فرد برای شناسایی متد، httpMethod برای استفاده، و path متد است (برای جزئیات نحوه استفاده از ویژگی path برای محاسبه آدرس کامل متد، به بخش Compose a request مراجعه کنید). علاوه بر این ویژگی‌های متد کلی، چند ویژگی وجود دارد که متد را با بخش‌های دیگر در سند Discovery مرتبط می‌کند:

محدوده ها

بخش auth که قبلاً در این مستندات تعریف شده است حاوی اطلاعاتی در مورد تمام حوزه های پشتیبانی شده توسط یک API خاص است. اگر متدی از یکی از این حوزه ها پشتیبانی کند، دارای یک آرایه scopes خواهد بود. یک ورودی در این آرایه برای هر محدوده پشتیبانی شده توسط متد وجود دارد.

توجه داشته باشید که انتخاب یک auth scope برای استفاده در برنامه شما به عوامل مختلفی بستگی دارد، از جمله اینکه کدام متدها فراخوانی می شوند و چه پارامترهایی همراه با متد ارسال می شوند. بنابراین، تصمیم گیری در مورد اینکه از کدام محدوده استفاده شود به توسعه دهنده واگذار می شود. اکتشاف فقط اسنادی را مستند می کند که دامنه برای یک روش معتبر است.

درخواست و پاسخ

اگر روش دارای بدنه درخواست یا پاسخ باشد، این موارد به ترتیب در بخش request یا response مستند می شوند. برای مثال، برای متد enable ، محتوای بخش request نشان می‌دهد که درخواست روش توسط یک طرح JSON با شناسه EnableServiceRequest تعریف شده است. این طرح را می توان در بخش طرحواره های سطح بالا یافت.

پارامترها

اگر روشی دارای پارامترهایی باشد که باید توسط کاربر مشخص شود، این پارامترها در قسمت parameters سطح روش ثبت می شوند. این بخش حاوی نگاشت کلید/مقدار نام پارامتر به جزئیات بیشتر در مورد آن پارامتر است.

برای مثال، یک پارامتر برای متد enable وجود دارد: name . پارامترها می توانند در path یا query URL قرار گیرند. ویژگی location نشان می دهد که کتابخانه مشتری باید این پارامتر را در کجا قرار دهد.

بسیاری از ویژگی‌های دیگر پارامتر را توصیف می‌کنند، از جمله type داده‌های پارامتر (مفید برای زبان‌هایی با تایپ قوی)، اینکه آیا پارامتر required است یا خیر، و اینکه آیا پارامتر یک عدد است یا خیر. برای جزئیات بیشتر در مورد این ویژگی ها به مستندات مرجع این API مراجعه کنید.

ترتیب پارامترها

راه‌های زیادی برای ساختاربندی رابط‌های کتابخانه‌های مشتری وجود دارد. یک راه این است که یک متد با هر پارامتر API در امضای متد داشته باشید. با این حال، از آنجایی که JSON یک فرمت نامرتب است، دانستن اینکه چگونه پارامترها را در امضای متد مرتب کنید از نظر برنامه‌نویسی دشوار است. آرایه parameterOrder ترتیب پارامترهای ثابتی را برای درخواست ارائه می دهد. آرایه نام هر پارامتر را به ترتیب اهمیت فهرست می کند. می تواند شامل پارامترهای مسیر یا پرس و جو باشد، اما هر پارامتر در آرایه مورد نیاز است.

بارگذاری رسانه

اگر روشی از آپلود رسانه مانند تصاویر، صدا یا ویدیو پشتیبانی می کند، مکان و پروتکل های پشتیبانی شده برای آپلود آن رسانه در بخش mediaUpload مستند می شوند. این بخش شامل جزئیاتی در مورد اینکه کدام پروتکل های آپلود پشتیبانی می شوند و اطلاعاتی در مورد نوع رسانه ای که می توان آپلود کرد، می باشد.

روش enable شامل بخش mediaUpload نیست. با این حال، یک بخش mediaUpload معمولی ممکن است به شکل زیر باشد:

"supportsMediaUpload": true,
"mediaUpload": {
  "accept": [
    "image/*"
  ],
  "maxSize": "10MB",
  "protocols": {
    "simple": {
      "multipart": true,
      "path": "/upload/storage/v1beta1/b/{bucket}/o"
    },
    "resumable": {
      "multipart": true,
      "path": "/resumable/upload/storage/v1beta1/b/{bucket}/o"
    }
  }
}

در مثال بالا، ویژگی supportsMediaUpload یک مقدار بولی است که تعیین می کند آیا روش از آپلود رسانه پشتیبانی می کند یا خیر. اگر مقدار درست باشد، بخش mediaUpload انواع رسانه‌های قابل آپلود را مستند می‌کند.

ویژگی accept فهرستی از محدوده‌های رسانه است که تعیین می‌کند کدام نوع mime برای آپلود قابل قبول است. نقطه پایانی نشان داده شده در مثال بالا هر فرمت تصویری را می پذیرد.

ویژگی maxSize حداکثر اندازه یک آپلود را دارد. مقدار یک رشته در واحدهای مگابایت، گیگابایت یا ترابایت است. در مثال بالا، آپلودها به حداکثر اندازه 10 مگابایت محدود شده است. توجه داشته باشید که این مقدار سهمیه ذخیره‌سازی باقی‌مانده یک کاربر را برای آن API منعکس نمی‌کند، بنابراین حتی اگر آپلود کمتر از maxSize باشد، کتابخانه سرویس گیرنده همچنان باید برای رسیدگی به آپلودی که به دلیل فضای ناکافی ناموفق است، آماده باشد.

بخش protocols پروتکل‌های آپلود را که یک روش پشتیبانی می‌کند فهرست می‌کند. پروتکل simple به سادگی ارسال رسانه به نقطه پایانی داده شده در یک درخواست HTTP است. پروتکل resumable به این معنی است که نقطه پایانی داده شده در path URI از پروتکل بارگذاری مجدد پشتیبانی می کند. اگر ویژگی multipart true باشد، نقطه پایانی بارگذاری‌های چند قسمتی را می‌پذیرد، به این معنی که هم درخواست JSON و هم رسانه می‌توانند در یک بدنه چندپارتی/مرتبط با هم پیچیده شوند و با هم ارسال شوند. توجه داشته باشید که هر دو پروتکل simple و resumable ممکن است از آپلود چند قسمتی پشتیبانی کنند.

ویژگی path یک الگوی URI است و باید مانند ویژگی path برای متد، همانطور که در بخش Compose a request توضیح داده شده است، گسترش یابد.

دانلود رسانه

اگر روشی از بارگیری رسانه مانند تصاویر، صدا یا ویدیو پشتیبانی می کند، با پارامتر supportsMediaDownload نشان داده می شود:

"supportsMediaDownload": true,

هنگام دانلود رسانه باید پارامتر alt query را در URL درخواست روی media تنظیم کنید.

اگر ویژگی useMediaDownloadService متد API true است، برای جلوگیری از تغییر مسیر، /download قبل از servicePath وارد کنید. برای مثال، مسیر دانلود /download/youtube/v3/captions/{id} است اگر الحاق servicePath و path /youtube/v3/captions/{id} باشد. توصیه می شود حتی زمانی که useMediaDownloadService نادرست است، URL دانلود رسانه را با /download بسازید.

توجه: برای یک روش API مجاز است که از دانلود و آپلود رسانه پشتیبانی کند. منطق ساخت URL درخواست برای آپلود و دانلود رسانه مستقل عمل می کند و با یکدیگر تداخلی ندارد. در نتیجه، چنین روش API دارای یک آدرس /download/... برای دانلود رسانه و یک /upload/... برای آپلود رسانه خواهد بود. با این حال، نمی توان در یک درخواست واحد بارگذاری و دانلود رسانه را انجام داد.

پارامترهای رایج

سند کشف سطح بالا حاوی یک ویژگی parameters است. این بخش مشابه بخش پارامترهای هر متد است، اما این پارامترها را می توان برای هر روشی در API اعمال کرد.

به عنوان مثال، متدهای get و list از سرویس Usage API می‌توانند یک پارامتر prettyPrint در پارامترهای درخواست داشته باشند، که پاسخ همه آن متدها را در قالبی قابل خواندن برای انسان قالب‌بندی می‌کند. در اینجا لیستی از پارامترهای رایج آمده است:

پارامتر	معنی	یادداشت ها	قابلیت کاربرد
`access_token`	نشانه OAuth 2.0 برای کاربر فعلی.	یکی از راه های ممکن برای ارائه توکن OAuth 2.0.
`alt`	قالب داده برای پاسخ.	مقادیر معتبر: `json` ، `atom` ، `csv` . مقدار پیش‌فرض: در هر API متفاوت است. همه مقادیر برای هر API در دسترس نیستند.	برای همه عملیات برای همه منابع اعمال می شود.
`callback`	عملکرد برگشت به تماس	نام تابع فراخوانی جاوا اسکریپت که پاسخ را مدیریت می کند. در درخواست های جاوا اسکریپت JSON-P استفاده می شود.
`fields`	انتخابگر که زیر مجموعه ای از فیلدها را برای درج در پاسخ مشخص می کند.	برای عملکرد بهتر استفاده کنید.
`key`	کلید API. (الزامی)	لازم است مگر اینکه توکن OAuth 2.0 ارائه دهید. کلید API شما پروژه شما را شناسایی می کند و دسترسی، سهمیه و گزارش های API را در اختیار شما قرار می دهد. کلید API پروژه خود را از کنسول APIs دریافت کنید.
`prettyPrint`	پاسخ را با شناسه ها و شکستگی ها برمی گرداند.	اگر `true` پاسخ را در قالبی قابل خواندن برای انسان برمی‌گرداند. مقدار پیش‌فرض: در هر API متفاوت است. هنگامی که این `false` است، می تواند اندازه بار پاسخ را کاهش دهد، که ممکن است منجر به عملکرد بهتر در برخی از محیط ها شود.
`quotaUser`	جایگزین `userIp` .	به شما امکان می دهد سهمیه های هر کاربر را از یک برنامه سمت سرور حتی در مواردی که آدرس IP کاربر ناشناخته است، اعمال کنید. به عنوان مثال، این می تواند در مورد برنامه هایی رخ دهد که از طرف یک کاربر، cron jobs را در App Engine اجرا می کنند. شما می توانید هر رشته دلخواه را که به طور منحصر به فرد کاربر را شناسایی می کند، انتخاب کنید، اما محدود به 40 کاراکتر است. در صورت ارائه هر دو، `userIp` لغو می کند. درباره محدودیت استفاده بیشتر بیاموزید.
`userIp`	آدرس IP کاربر نهایی که تماس API برای او انجام می شود.	به شما امکان می دهد هنگام فراخوانی API از یک برنامه سمت سرور، سهمیه های هر کاربر را اعمال کنید. درباره محدودیت استفاده بیشتر بیاموزید.

اسناد درون خطی

هر سند Discovery با تعدادی فیلد description حاشیه نویسی می شود که اسناد درون خطی را برای API ارائه می کند. فیلدهای description را می توان برای عناصر API زیر یافت:

خود API
دامنه های OAuth
طرحواره های منابع
روش های API
پارامترهای روش
مقادیر قابل قبول برای پارامترهای خاص

این فیلدها مخصوصاً در صورتی مفید هستند که می‌خواهید از سرویس Google APIs Discovery برای تولید اسناد قابل خواندن توسط انسان برای یک کتابخانه مشتری استفاده کنید - به عنوان مثال، JavaDoc.

از Discovery API استفاده کنید با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.