درحال مشاهده اسناد Apigee Edge هستید.
به
اسناد Apigee X بروید. اطلاعات
نسخه: 2.0.0
برای دسترسی به Google APIs که مشخص می‌کنید، با Google اصالت‌سنجی کنید.
از این افزونه برای دریافت کد (OAuth یا JWT) برای خدمات Google Cloud استفاده کنید، سپس از کد برای تماس‌های بعدی با Google API استفاده کنید، مثلاً بااستفاده از خط‌مشی ServiceCallout.
برای مثال، در یک پراکسی API می‌توانید با این افزونه یک کد دریافت کنید، کد را بااستفاده از خط‌مشی PopulateCache در حافظه نهان ذخیره کنید، سپس کد را بااستفاده از خط‌مشی ServiceCallout برای دسترسی به خدمات Google Cloud از درون جریان پراکسی API ارسال کنید.
پیش‌نیازها
این محتوا مرجعی برای پیکربندی و استفاده از این افزونه ارائه می‌دهد. قبل‌از استفاده از افزونه از یک پراکسی API بااستفاده از خط‌مشی ExtensionCallout، باید:
مطمئن شوید حسابی که افزونه از آن استفاده می‌کند -- حسابی که با حساب سرویسی که برای اطلاعات اعتباری استفاده می‌کنید نشان داده می‌شود -- به سرویس‌های Google Cloud که افزونه با آن‌ها اصالت‌سنجی می‌کند دسترسی داشته باشد.
از «کنسول Google Cloud» برای تولید کلید حساب سرویس استفاده کنید.
از محتوای فایل JSON کلید حساب خدمات حاصل‌شده هنگام افزودن و پیکربندی افزونه بااستفاده از مرجع پیکربندی استفاده کنید.
درباره اصالت‌سنجی با Google Cloud
این افزونه با نشان دادن عضو مشخصی که در پروژه Google Cloud شما تعریف شده است، از Google Cloud درخواست اصالت‌سنجی می‌کند. هنگام پیکربندی این افزونه، از فایل JSON حساب سرویس آن عضو پروژه استفاده می‌کنید.
در نتیجه، این افزونه فقط به منابعی دسترسی خواهد داشت که آن عضو اجازه دسترسی به آن‌ها را دارد. به‌عبارت دیگر، اصالت‌سنجی موفق توسط این افزونه به مطابقت بین اجازه‌های اعطاشده در «کنسول Google Cloud» و دسترسی درخواست‌شده توسط افزونه (ازطریق محدوده‌ها یا مخاطب) در زمان اجرا بستگی دارد.
به‌طورکلی، مراحل اصالت‌سنجی برای دسترسی به «میاناهای برنامه‌سازی کاربردی» از این افزونه به این صورت است:
مطمئن شوید حساب سرویس عضوی که این افزونه نماینده آن است به منبع Google موردنظرتان برای دسترسی دسترسی داشته باشد. می‌توانید از صفحه «مدیریت هویت و دسترسی‌ها در Cloud» (Cloud IAM) در «کنسول Google Cloud» برای اعطای نقش‌ها به عضو پروژه‌ای که این افزونه نشان می‌دهد استفاده کنید.
هنگام پیکربندی این افزونه، از کلید حساب سرویس آن عضو JSON استفاده کنید.
هنگام پیکربندی خط‌مشی «افزونه تماس» برای استفاده از این افزونه، فقط برای منابعی که عضو پروژه شما به آن‌ها دسترسی دارد درخواست اصالت‌سنجی کنید.
نمونه‌ها
مثال‌های زیر نشان می‌دهد که چگونه بااستفاده از خط‌مشی «برنامه‌های ترویجی» با Google Cloud اصالت‌سنجی کنید.
دریافت کد دسترسی
در مثال زیر، کنش getOauth2AccessToken افزونه یک کد را برای استفاده در درخواست‌های Cloud Translation API بازیابی می‌کند.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Get-Access-Token">
<DisplayName>Get Access Token</DisplayName>
<Connector>google-auth</Connector>
<Action>getOauth2AccessToken</Action>
<Input><![CDATA[{
"scope" : [
"https://www.googleapis.com/auth/cloud-translation"
]
}]]></Input>
<Output>google.credentials</Output>
</ConnectorCallout>
مقدار پاسخ چیزی شبیه این است:
{
"access_token":"ya29.c.ElpSB...BMgkALBJ0kou-8",
"token_type":"Bearer",
"expiresInSec": 3600
}
خط‌مشی AssignMessage زیر مقدار پاسخ را از خط‌مشی ExtensionCallout بازیابی می‌کند و آن را در محتوای پاسخ کپی می‌کند. این کار می‌تواند برای اشکال‌زدایی مفید باشد. در عمل، ممکن است نخواهید نشان را به مشتری برگردانید.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="false" enabled="true" name="Retrieve-Auth-Token">
<DisplayName>Retrieve Auth Token</DisplayName>
<AssignTo type="response" createNew="false"/>
<Set>
<Payload contentType="application/json">{google.credentials.access_token}</Payload>
</Set>
</AssignMessage>
ذخیره کردن کد دسترسی در حافظه نهان
برای جلوگیری از تماس‌های غیرضروری برای بازیابی نمودار، نموداری را که دریافت می‌کنید ذخیره کنید. برای تماس‌های بعدی که به نمودار نیاز دارند، بازیابی نمودار از حافظه نهان Apigee Edge سریع‌تر از دریافت نمودار جدید است. وقتی کد ذخیره‌شده منقضی شد، کد جدیدی را بازیابی کنید و حافظه نهان را با آن بازآوری کنید.
کد زیر از یک پراکسی API نمونه نشان می‌دهد که چگونه یک کد ذخیره‌شده را برای فراخوانی Google Translation API با خط‌مشی ServiceCallout تنظیم و استفاده کنید. هر نمونه کد در اینجا مربوط به خط‌مشی متفاوتی در جریان است.
خط‌مشی‌های زیر در توالی شرح‌داده‌شده توسط XML جریان زیر اجرا می‌شوند:
<Request>
<!-- Attempt to get a token from the cache. -->
<Step>
<Name>Get-Cached-Auth-Token</Name>
</Step>
<!-- Only execute the following ExtensionCallout policy if the call to the
cache couldn't retrieve a cached token. -->
<Step>
<Name>Google-Auth-Callout</Name>
<Condition>lookupcache.Get-Cached-Auth-Token.cachehit is false</Condition>
</Step>
<!-- Only execute the following PopulateCache policy if the call to the
cache couldn't retrieve a cached token. -->
<Step>
<Name>Cache-Auth-Token</Name>
<Condition>lookupcache.Get-Cached-Auth-Token.cachehit is false</Condition>
</Step>
<!-- Use the ServiceCallout policy to call the translate API. -->
<Step>
<Name>Translate-Text</Name>
</Step>
</Request>
خط‌مشی LookupCache زیر تلاش می‌کند تا از حافظه نهان یک کد دریافت کند. اگر قبلاً نشان دریافت و ذخیره شده باشد، این خط‌مشی آن را برای استفاده توسط پراکسی API دریافت خواهد کرد.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <LookupCache async="false" continueOnError="false" enabled="true" name="Get-Cached-Auth-Token"> <DisplayName>Get Cached Auth Token</DisplayName> <!-- Give cache key and scope to specify the entry for the cached token. --> <CacheKey> <Prefix/> <KeyFragment>gcp_translate_token_</KeyFragment> </CacheKey> <Scope>Exclusive</Scope> <!-- Assign the retrieved token (if any) to a variable, where it can be retrieved by policies. --> <AssignTo>cloud.translation.auth.token</AssignTo> </LookupCache>اگر جستجوی حافظه نهان یک کد ذخیره‌شده را بازیابی نکند، خط‌مشی «بازده تماسی افزونه» زیر کد OAuth جدیدی را بازیابی می‌کند و Google Cloud Translation API را به‌عنوان محدوده کد مشخص می‌کند. اگر اعتبارنامه حساب سرویس استفاده‌شده هنگام پیکربندی افزونه
Google-Auth-Calloutنشان‌دهنده عضو پروژه‌ای باشد که به API دسترسی دارد، Google Cloud یک کد معتبر برمی‌گرداند.<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ConnectorCallout async="false" continueOnError="true" enabled="true" name="Google-Auth-Callout"> <DisplayName>Google-Auth-Callout</DisplayName> <Connector>example-auth-extension</Connector> <Action>getOauth2AccessToken</Action> <Input><![CDATA[{ "scope" : ["https://www.googleapis.com/auth/cloud-translation"] }]]></Input> <Output parsed="false">cloud.translation.auth.token</Output> </ConnectorCallout>پس‌از اینکه خط‌مشی ExtensionCallout کد جدیدی را بازیابی کرد، خط‌مشی PopulateCache آن را برای استفاده بعدی توسط خط‌مشی‌های موجود در پراکسی API ذخیره می‌کند.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <PopulateCache async="false" continueOnError="false" enabled="true" name="Cache-Auth-Token"> <DisplayName>Cache Auth Token</DisplayName> <Properties/> <!-- Set cache key information to specify a unique key for this entry. --> <CacheKey> <Prefix/> <KeyFragment>gcp_translate_token_</KeyFragment> </CacheKey> <Scope>Exclusive</Scope> <ExpirySettings> <TimeoutInSec>5</TimeoutInSec> </ExpirySettings> <!-- Get the token to cache from the variable where the ExtensionCallout put it. --> <Source>cloud.translation.auth.token</Source> </PopulateCache>
کنش‌ها
getOauth2AccessToken
کد دسترسی OAuth 2.0 را دریافت می‌کند. از این کنش برای پشتیبانی از OAuth دو سر بین پراکسی API و Google APIs خود زمانی‌که Google APIs به کد OAuth نیاز دارد استفاده کنید.
در OAuth دوپایه، این کنش افزونه با اصالت‌سنجی با Google بااستفاده از JSON حساب سرویس (این JSON را هنگام پیکربندی این افزونه اضافه می‌کنید) یک کد OAuth را بازیابی می‌کند. پس‌از اینکه این کنش نشان OAuth را بازیابی کرد، پراکسی API شما می‌تواند از این نشان برای فراخوانی کردن «میاناهای برنامه‌سازی کاربردی Google» استفاده کند و درواقع میاناهای برنامه‌سازی کاربردی را ازطرف حساب سرویس Google فراخوانی کند.
دسترسی به Google Cloud APIs ازطریق محدوده‌های فهرست‌شده در محدوده‌های OAuth 2.0 برای Google APIs فیلتر می‌شود.
برای اطلاعات بیشتر درباره تعاملات سرور به سرور با OAuth 2.0، به استفاده از OAuth 2.0 برای برنامه‌های سرور به سرور مراجعه کنید
نحو
<Action>getOauth2AccessToken</Action>
<Input><![CDATA[{
"scope" : [
"scope1",
"scope2"
]
}]]></Input>
مثال
در مثال زیر، کنش getOauth2AccessToken افزونه یک کد را برای استفاده در درخواست‌های Cloud Translation API بازیابی می‌کند.
<Action>getOauth2AccessToken</Action>
<Input><![CDATA[{
"scope" : [
"https://www.googleapis.com/auth/cloud-translation"
]
}]]></Input>
پارامترهای درخواست
| پارامتر | شرح | نوع | پیش‌فرض | الزامی |
|---|---|---|---|---|
| حوزه | آرایه‌ای از محدوده‌های OAuth 2.0. برای اطلاعات بیشتر درباره محدوده‌ها، محدوده‌های OAuth 2.0 برای Google APIs را ببینید. | آرایه | ["https://www.googleapis.com/auth/cloud-platform"] که دسترسی به همه میاناهای برنامه‌سازی کاربردی را که حساب سرویس به آن‌ها دسترسی دارد اعطا می‌کند. |
شماره. |
پاسخ
شیئی که حاوی کد دسترسی، نوع آن، و تاریخ انقضای آن در قالب زیر است:
{
"accessToken": "ewogICJ0eXB...C5jb20iCn0K",
"token_type": "Bearer",
"expiresInSec": 3600
}
خصوصیت‌های پاسخ
| پارامتر | شرح | پیش‌فرض | الزامی |
|---|---|---|---|
| accessToken | کد دسترسی OAuth 2.0. | خالی | بله |
| tokenType | نوع کد. | حامل | بله |
| expiresInSec | تعداد ثانیه‌ها تا انقضای رمز. | 3600 | بله |
getJWTAccessToken
کد دسترسی «توکن وب JSON» (JWT) را دریافت می‌کند. اگر میانای برنامه‌سازی کاربردی که می‌خواهید فراخوانی کنید تعریف خدماتی منتشرشده در مخزن GitHub ویژه Google APIs داشته باشد، می‌توانید از این کد برای اصالت‌سنجی با Google APIs استفاده کنید.
با برخی‌از «میاناهای برنامه‌سازی کاربردی Google»، می‌توانید بااستفاده از JWT امضاشده مستقیماً به‌عنوان یک کد حامل، به‌جای کد دسترسی OAuth 2.0، تماس‌های مجاز API برقرار کنید. وقتی این امکان وجود داشته باشد، می‌توانید قبل‌از برقراری تماس با API، از ارسال درخواست شبکه به سرور مجوز Google خودداری کنید.
برای اطلاعات بیشتر درباره اصالت‌سنجی با ژتون دسترسی JWT، به استفاده از OAuth 2.0 برای برنامه‌های سرور به سرور مراجعه کنید.
نحو
<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
"audience" : "audience"
}]]></Input>
مثال: نشانی وب «تابع ابری»
در مثال زیر، کنش getOauth2AccessToken افزونه یک کد را برای استفاده در درخواست‌های Cloud Translation API بازیابی می‌کند.
<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
"audience" : "https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/FUNCTION_NAME"
}]]></Input>
مثال: شناسه کارخواه ایمن‌شده با Cloud IAP
در مثال زیر، کنش getOauth2AccessToken افزونه یک کد را برای استفاده در درخواست‌های Cloud Translation API بازیابی می‌کند.
<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
"audience" : "Cloud-IAP-secured-client-ID"
}]]></Input>
پارامترهای درخواست
| پارامتر | شرح | پیش‌فرض | الزامی |
|---|---|---|---|
| مخاطبین | گیرنده موردنظر نشان. این می‌تواند شامل شناسه کارخواه ایمن‌شده با Cloud IAP، نشانی وب Cloud Functions باشد. | خالی | بله |
پاسخ
{
"accessToken": "token",
"tokenType": "Bearer",
"expiresInSec": 3600
}
خصوصیت‌های پاسخ
| پارامتر | شرح | پیش‌فرض | الزامی |
|---|---|---|---|
| accessToken | کد دسترسی. | خالی | بله |
| tokenType | نوع کد. | حامل | بله |
| expiresInSec | انقضا به ثانیه. | 3600 | بله |
مرجع پیکربندی
هنگام پیکربندی و استقرار این افزونه برای استفاده در پراکسی‌های API، از موارد زیر استفاده کنید. برای مراحل پیکربندی افزونه بااستفاده از کنسول Apigee، به افزودن و پیکربندی افزونه مراجعه کنید.
دارایی‌های افزونه مشترک
ویژگی های زیر برای هر افزونه وجود دارد.
| ویژگی | شرح | پیش فرض | ضروری |
|---|---|---|---|
name | نامی که به این پیکربندی افزونه می‌دهید. | هیچ یک | آره |
packageName | نام بسته افزودنی همانطور که توسط Apigee Edge داده شده است. | هیچ یک | آره |
version | شماره نسخه بسته برنامه افزودنی که از آن یک برنامه افزودنی را پیکربندی می کنید. | هیچ یک | آره |
configuration | مقدار پیکربندی مخصوص افزونه ای که اضافه می کنید. به ویژگی های این بسته برنامه افزودنی مراجعه کنید | هیچ یک | آره |
دارایی‌های این بسته افزونه
مقادیر مشخصه‌های پیکربندی زیر را که مختص این افزونه است مشخص کنید.
| دارایی | شرح | پیش‌فرض | الزامی |
|---|---|---|---|
| اطلاعات اعتباری | وقتی در کنسول Apigee Edge وارد می‌شود، این محتوای کامل فایل JSON کلید حساب خدمات شما است. وقتی بااستفاده از «میانای برنامه‌سازی کاربردی مدیریت» ارسال می‌شود، مقدار کدبندی‌شده با base64 است که از کل فایل JSON کلید حساب سرویس تولید می‌شود. | خالی | بله |