برنامه افزودنی تأیید اعتبار Google

شما در حال مشاهده اسناد Apigee Edge هستید.
به مستندات Apigee X بروید . اطلاعات

نسخه: 1.0.2

برای دسترسی به API های Google که مشخص کرده اید، با Google احراز هویت کنید.

از این برنامه افزودنی برای به دست آوردن یک نشانه (OAuth یا JWT) برای سرویس‌های Google Cloud استفاده کنید، سپس از این رمز برای تماس‌های بعدی با Google API، مانند استفاده از خط‌مشی ServiceCallout استفاده کنید.

به عنوان مثال، در یک پراکسی API ممکن است رمزی با این پسوند دریافت کنید، رمز را با استفاده از خط مشی PopulateCache در حافظه پنهان ذخیره کنید، سپس رمز را از طریق خط مشی ServiceCallout ارسال کنید تا از درون یک جریان پراکسی API به خدمات Google Cloud دسترسی داشته باشید.

پیش نیازها

این محتوا مرجعی برای پیکربندی و استفاده از این پسوند ارائه می دهد. قبل از استفاده از برنامه افزودنی از یک پروکسی API با استفاده از خط مشی ExtensionCallout ، باید:

  1. مطمئن شوید که حسابی که برنامه افزودنی از آن استفاده می‌کند - حسابی که توسط حساب سرویسی که برای اعتبارنامه استفاده می‌کنید نشان داده می‌شود - به سرویس‌های Google Cloud دسترسی دارد که برنامه افزودنی با آنها احراز هویت می‌کند.

  2. از Google Cloud Console برای ایجاد یک کلید برای حساب سرویس استفاده کنید .

  3. هنگام افزودن و پیکربندی برنامه افزودنی با استفاده از مرجع پیکربندی، از محتویات فایل JSON کلید حساب سرویس حاصل استفاده کنید.

درباره احراز هویت با Google Cloud

این برنامه افزودنی با نشان دادن عضو خاصی که در پروژه Google Cloud شما تعریف شده است، از Google Cloud درخواست احراز هویت می کند. هنگام پیکربندی این افزونه، از فایل JSON حساب سرویس آن عضو پروژه استفاده می‌کنید.

در نتیجه، این برنامه افزودنی تنها به منابعی دسترسی خواهد داشت که آن عضو دارای مجوز است. به عبارت دیگر، احراز هویت موفقیت‌آمیز توسط این برنامه افزودنی به تطابق بین مجوزهای اعطا شده در Google Cloud Console و دسترسی درخواست شده توسط افزونه (از طریق دامنه یا مخاطب) در زمان اجرا بستگی دارد.

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

  1. مطمئن شوید که حساب سرویس عضوی که این برنامه افزودنی نشان می دهد به منبع Google که می خواهید به آن دسترسی داشته باشید دسترسی داشته باشد. می‌توانید از صفحه Cloud Identity and Access Management (Cloud IAM) در Google Cloud Console برای اعطای نقش به عضو پروژه که این برنامه افزودنی نشان می‌دهد استفاده کنید.

  2. هنگام پیکربندی این برنامه افزودنی از کلید JSON حساب سرویس آن عضو استفاده کنید.

  3. هنگام پیکربندی یک خط مشی ExtensionCallout برای استفاده از این برنامه افزودنی، فقط برای منابعی که عضو پروژه شما به آنها دسترسی دارد درخواست احراز هویت کنید.

نمونه ها

مثال‌های زیر نحوه احراز هویت با Google Cloud را با استفاده از خط‌مشی ExtensionCallout نشان می‌دهند.

یک نشانه دسترسی دریافت کنید

در مثال زیر، اقدام 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>

  1. سیاست 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>

  2. اگر جستجوی حافظه پنهان رمز ذخیره شده را بازیابی نکند، خط مشی ExtensionCallout زیر یک نشانه 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>

  3. پس از اینکه خط‌مشی 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 API زمانی که APIهای Google به یک نشانه OAuth نیاز دارند، استفاده کنید.

در OAuth دوپایه، این اقدام افزونه با احراز هویت با Google با استفاده از حساب سرویس JSON، یک نشانه OAuth را بازیابی می‌کند (وقتی این برنامه افزودنی را پیکربندی می‌کنید، JSON را اضافه می‌کنید). هنگامی که این اقدام نشانه OAuth را بازیابی کرد، پروکسی API شما می‌تواند از این رمز برای برقراری تماس با APIهای Google استفاده کند و عملاً APIها را از طرف حساب سرویس Google فراخوانی کند.

دسترسی به Google Cloud API از طریق محدوده‌های فهرست شده در حوزه‌های OAuth 2.0 برای Google API فیلتر می‌شود.

برای اطلاعات بیشتر درباره تعاملات سرور به سرور با 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 scopes for Google APIs را ببینید. آرایه ["https://www.googleapis.com/auth/cloud-platform"] ، که به همه API هایی که حساب سرویس به آنها دسترسی دارد، دسترسی می دهد. خیر

پاسخ

یک شی حاوی نشانه دسترسی، نوع آن و تاریخ انقضای آن به شکل زیر است: 

{
  "accessToken": "ewogICJ0eXB...C5jb20iCn0K",
  "token_type": "Bearer",
  "expiresInSec": 3600
}

ویژگی های پاسخگویی

پارامتر توضیحات پیش فرض مورد نیاز
AccessToken نشانه دسترسی OAuth 2.0. هیچ کدام بله
tokenType نوع توکن حامل بله
expiresInSec تعداد ثانیه تا انقضای توکن. 3600 بله

getJWTAccessToken

نشانه دسترسی JSON وب (JWT) را دریافت می کند. اگر APIی که می‌خواهید تماس بگیرید دارای تعریف سرویس منتشر شده در مخزن Google APIs GitHub باشد، می‌توانید از این نشانه برای احراز هویت با Google API استفاده کنید.

با برخی از APIهای Google، می‌توانید تماس‌های مجاز API را با استفاده از JWT امضا شده مستقیماً به‌عنوان توکن حامل، به جای نشانه دسترسی OAuth 2.0 برقرار کنید. در صورت امکان، می توانید قبل از برقراری تماس API از درخواست شبکه به سرور مجوز Google اجتناب کنید.

برای اطلاعات بیشتر درباره احراز هویت با یک نشانه دسترسی JWT، به استفاده از OAuth 2.0 برای برنامه های کاربردی سرور به سرور مراجعه کنید.

نحو 

<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
    "audience" : "audience"
}]]></Input>

مثال: URL تابع ابر

در مثال زیر، اقدام getOauth2AccessToken برنامه افزودنی، رمزی را برای استفاده در درخواست‌های Cloud Translation API بازیابی می‌کند. 

<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
  "audience" : "https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/FUNCTION_NAME"
}]]></Input>

مثال: Cloud IAP-secured client ID

در مثال زیر، اقدام getOauth2AccessToken برنامه افزودنی، رمزی را برای استفاده در درخواست‌های Cloud Translation API بازیابی می‌کند. 

<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
  "audience" : "Cloud-IAP-secured-client-ID"
}]]></Input>

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

پارامتر توضیحات پیش فرض مورد نیاز
مخاطب گیرنده مورد نظر توکن. این می تواند شامل شناسه سرویس گیرنده ایمن شده با Cloud IAP، URL عملکردهای ابری و غیره باشد. هیچ کدام بله

پاسخ 

{
  "accessToken": "token",
  "tokenType": "Bearer",
  "expiresInSec": 3600
}

ویژگی های پاسخگویی

پارامتر توضیحات پیش فرض مورد نیاز
AccessToken نشانه دسترسی هیچ کدام بله
tokenType نوع توکن حامل بله
expiresInSec انقضا در چند ثانیه 3600 بله

مرجع پیکربندی

هنگام پیکربندی و استقرار این افزونه برای استفاده در پراکسی های API از موارد زیر استفاده کنید. برای مراحل پیکربندی یک برنامه افزودنی با استفاده از کنسول Apigee، به افزودن و پیکربندی یک برنامه افزودنی مراجعه کنید.

ویژگی های رایج پسوند

ویژگی های زیر برای هر افزونه وجود دارد.

ویژگی شرح پیش فرض ضروری
name نامی که به این پیکربندی افزونه می‌دهید. هیچ یک آره
packageName نام بسته افزودنی همانطور که توسط Apigee Edge داده شده است. هیچ یک آره
version شماره نسخه بسته برنامه افزودنی که از آن یک برنامه افزودنی را پیکربندی می کنید. هیچ یک آره
configuration مقدار پیکربندی مخصوص افزونه ای که اضافه می کنید. به ویژگی های این بسته برنامه افزودنی مراجعه کنید هیچ یک آره

ویژگی های این بسته افزونه

مقادیری را برای خصوصیات پیکربندی زیر مخصوص این افزونه مشخص کنید.

اموال توضیحات پیش فرض مورد نیاز
اعتبارنامه وقتی در کنسول Apigee Edge وارد می‌شوید، کل محتوای فایل JSON کلید حساب کاربری شما است. هنگامی که از طریق API مدیریت ارسال می شود، یک مقدار کدگذاری شده با base64 است که از کل فایل JSON کلید حساب سرویس ایجاد می شود. هیچ کدام بله