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

با استفاده از API

مقدمه

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

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

اگر با مفاهیم Google APIs Discovery Service آشنا نیستید، باید قبل از شروع به کدنویسی، Getting Started را بخوانید.

قالب سند کشف

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

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

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

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

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

هر یک از این بخش های سند Discovery در زیر توضیح داده شده است. برای جزئیات بیشتر در مورد هر ملک به مستندات مرجع مراجعه کنید.

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

سند Discovery شامل مجموعه‌ای از ویژگی‌های خاص API است:

"kind": "discovery#restDescription",
"name": "servicemanagement",
"version": "v1",
"title": "Service Management API",
"description": "Google Service Management allows service producers to publish their services on Google Cloud Platform so that they can be discovered and used by service consumers.",
"protocol": "rest",
"rootUrl": "https://servicemanagement.googleapis.com/. Root URL under which all API services live",
"servicePath": "",

این ویژگی‌های سطح 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.read-only": {
        "description": "View your data across Google Cloud Platform services"
      },
      "https://www.googleapis.com/auth/service.management.readonly": {
        "description": "View your Google API service configuration"
      },
      "https://www.googleapis.com/auth/cloud-platform": {
        "description": "View and manage your data across Google Cloud Platform services"
      },
      "https://www.googleapis.com/auth/service.management": {
        "description": "Manage your Google API service configuration"
      }
    }
  }
}

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

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

عملیات یک API بر روی اشیاء داده ای به نام resources عمل می کند. سند Discovery بر اساس مفهوم منابع ساخته شده است. هر سند Discovery یک بخش resources سطح بالایی دارد که تمام منابع مرتبط با API را گروه بندی می کند. به عنوان مثال، Google Cloud Service Management API دارای یک منبع services و یک منبع operations تحت resources سطح بالا است، منبع services دارای سه منبع فرعی، configs ، rollouts و consumers است:

"resources": {
  "services": {
    // Methods and sub-resources associated with the services resource
    "configs": {
      // Methods and sub-resources associated with the services.configs resource
    },
    "rollouts": {
      // Methods and sub-resources associated with the services.rollouts resource
    },
    "consumers": {
      // Methods and sub-resources associated with the services.consumers resource
    }
  },
  "operations": {
    // Methods and sub-resources associated with the operations resource
  }
}

در داخل هر بخش منبع، روش های مرتبط با آن منبع وجود دارد. به عنوان مثال، Google Cloud Service Management API دارای سه روش مرتبط با منبع services.rollouts است: get ، list کردن و create .

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

"schemas": {
  "Rollout": {
    // JSON Schema of the Rollout resource.
  }
}

APIs Discovery Service از JSON Schema draft-03 برای نمایش طرحواره خود استفاده می کند. در اینجا یک قطعه از طرحواره JSON برای منبع Url به همراه یک منبع پاسخ واقعی آمده است:

طرح JSON منبع عرضه:

پاسخ واقعی منبع عرضه:

{
  "Rollout": {
    "id": "Rollout",
    "type": "object",
    "description": "...",
    "properties": {
      "serviceName": {
        "type": "string",
        "description": "..."
      },
      "rolloutId": {
        "type": "string",
        "description": "..."
      },
      "status": {
        "type": "string",
        "enum": [
          "ROLLOUT_STATUS_UNSPECIFIED",
          "IN_PROGRESS",
          "SUCCESS",
          "CANCELLED",
          "FAILED",
          "PENDING",
          "FAILED_ROLLED_BACK"
        ],
        "enumDescriptions": [
          ...
        ],
        "description": "..."
      },
      "trafficPercentStrategy": {
        "$ref": "TrafficPercentStrategy",
        "description": "..."
      },
      "deleteServiceStrategy": { ... },
      "createTime": { ... },
      "createdBy": { ... }
    }
  }
}

{
  "serviceName": "discovery.googleapis.com",
  "rolloutId": "2020-01-01R0",
  "status": "SUCCESS",
  "trafficPercentStrategy":{
    "precentages":{
      "2019-12-01R0": 70.00,
      "2019-11-01R0": 30.00
    }
  }
}

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

طرحواره ها همچنین ممکن است حاوی ارجاع به طرحواره های دیگر باشند. اگر در حال ساختن یک کتابخانه کلاینت هستید، این می تواند به شما کمک کند تا به طور موثر اشیاء یک API را در کلاس های مدل داده خود مدل سازی کنید. در مثال Rollout بالا، ویژگی trafficPercentStrategy در واقع ارجاع به طرحی با شناسه TrafficPercentStrategy است. اگر به بخش schemas نگاه کنید، طرح TrafficPercentStrategy را خواهید دید. مقدار این طرحواره را می توان با ویژگی trafficPercentStrategy در منبع Rollout جایگزین کرد (توجه داشته باشید که دستور $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 ، list و create را مستند می کند:

"methods": {
  "get": { //details about the "get" method },
  "list": { //details about the "list" method },
  "create": { //details about the "create" method }
}

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

"get": {
  "id": "servicemanagement.services.rollouts.get",
  "path": "v1/services/{serviceName}/rollouts/{rolloutId}",
  "flatPath": "v1/services/{serviceName}/rollouts/{rolloutId}",
  "httpMethod": "GET",
  "description": "Gets a service configuration rollout.",
  "response": { "$ref": "Rollout" },
  "parameters": { // parameters related to the method },
  "parameterOrder": [ // parameter order related to the method ],
  "scopes": [ // OAuth 2.0 scopes applicable to this method ],
  "mediaUpload": { // optional media upload information },
},

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

محدوده ها

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

"scopes": [
  "https://www.googleapis.com/auth/cloud-platform",
  "https://www.googleapis.com/auth/cloud-platform.read-only",
  "https://www.googleapis.com/auth/service.management",
  "https://www.googleapis.com/auth/service.management.readonly"
]

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

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

اگر روش دارای بدنه درخواست یا پاسخ باشد، این موارد به ترتیب در بخش request یا response مستند می شوند. get مثال بالا، متد یک بدنه response دارد:

"response": {
  "$ref": "Rollout"
}

نحو بالا نشان می دهد که بدنه پاسخ توسط یک طرحواره JSON با شناسه Rollout تعریف شده است. این طرح را می توان در بخش طرحواره های سطح بالا یافت. هر دو بدنه درخواست و پاسخ از دستور $ref برای ارجاع به طرحواره ها استفاده می کنند.

مولفه های

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

"parameters": {
  "serviceName": {
    "type": "string",
    "description": "Required. The name of the service.",
    "required": true,
    "location": "path"
  },
  "rolloutId": { ... }
},
"parameterOrder": [
  "serviceName",
  "rolloutId"
]

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

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

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

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

public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters);

اولین مقدار در آرایه parameterOrder ، serviceName ، همچنین اولین عنصر در امضای متد است. اگر پارامترهای دیگری در آرایه parameterOrder وجود داشته باشد، آنها به دنبال پارامتر serviceName می روند. از آنجایی که آرایه parameterOrder فقط شامل پارامترهای مورد نیاز است، تمرین خوبی است که راهی را برای کاربران در نظر بگیرید تا پارامترهای اختیاری را نیز مشخص کنند. مثال بالا این کار را با نقشه optionalParameters انجام می دهد.

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

اگر روشی از آپلود رسانه مانند تصاویر، صدا یا ویدیو پشتیبانی می کند، مکان و پروتکل های پشتیبانی شده برای آپلود آن رسانه در بخش 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 بسازید.

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

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

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

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

امکانات

مواردی وجود دارد که APIها از ویژگی های سفارشی خارج از محدوده بقیه سند Discovery پشتیبانی می کنند. اینها در آرایه features ها جمع آوری می شوند. آرایه ویژگی ها حاوی یک برچسب رشته ای برای هر ویژگی خاص است که توسط API پشتیبانی می شود. در حال حاضر، dataWrapper تنها ویژگی پشتیبانی شده است، اما سایر ویژگی‌ها ممکن است در آینده پشتیبانی شوند.

"features": dataWrapper

ویژگی dataWrapper نشان می‌دهد که تمام درخواست‌ها و پاسخ‌ها از API در یک شی data JSON پیچیده شده‌اند. این یکی از ویژگی های API های قدیمی گوگل است، اما در حال منسوخ شدن است. APIهای زیر از ویژگی dataWrapper پشتیبانی می‌کنند: Moderator v1 و Translate v2 .

به عنوان یک توسعه دهنده کتابخانه مشتری، اگر یک API از ویژگی "dataWrapper" پشتیبانی می کند، باید کارهای زیر را انجام دهید:

در مورد درخواست ها: منبع درخواست را در یک شی data JSON بپیچید.
در پاسخ ها: منبع را در یک شی JSON data پیدا کنید.

طرحواره های موجود در سند Discovery حاوی بسته بندی داده نیستند، بنابراین باید به صراحت آنها را اضافه و حذف کنید. به عنوان مثال، فرض کنید یک API با منبعی به نام "Foo" وجود دارد که به شکل زیر است:

{
  "id": 1,
  "foo": "bar"
}

قبل از درج این منبع با استفاده از API، باید آن را در یک عنصر داده قرار دهید:

{
  "data": {
    "id": 1,
    "foo": "bar"
  }
}

از طرف دیگر، هنگامی که یک پاسخ از API دریافت می کنید، شامل بسته بندی داده نیز می شود:

{
  "data": {
    "id": 1,
    "foo": "bar"
  }
}

برای به دست آوردن منبع تعریف شده توسط طرحواره، باید پوشش داده را حذف کنید:

{
  "id": 1,
  "foo": "bar"
}

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

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

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

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

مراحل بعدی

ساخت کتابخانه مشتری