VerificationAPIKey politikası

Apigee Edge belgelerini görüntülüyorsunuz.
Apigee X belgelerine gidin. info

Ne?

API anahtarını doğrulama politikası, API anahtarlarının çalışma zamanında doğrulanmasını zorunlu kılarak yalnızca onaylanmış API anahtarlarına sahip uygulamaların API'lerinize erişmesine olanak tanır. Bu politika, API anahtarlarının geçerli olmasını, iptal edilmemesini ve API ürünlerinizle ilişkili belirli kaynakları kullanmak için onaylanmasını sağlar.

Örnekler

Sorgu parametresindeki anahtar

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>

Bu örnekte politika, API anahtarının request.queryparam.apikey adlı bir akış değişkeninde bulunmasını bekliyor. request.queryparam.{name} değişkeni, istemci isteğinde iletilen bir sorgu parametresinin değeriyle doldurulan standart bir Edge akışı değişkenidir.

Aşağıdaki curl komutu, API anahtarını bir sorgu parametresinde iletir:

curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

Başlıktaki anahtar

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>

Bu örnekte politika, API anahtarının request.header.x-apikey adlı bir akış değişkeninde bulunmasını bekliyor. request.header.{name} değişkeni, istemci isteğinde iletilen bir başlığın değeriyle doldurulan standart bir Edge akışı değişkenidir.

Aşağıdaki cURL, API anahtarının üstbilgiye nasıl iletileceğini gösterir:

curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"

Değişkendeki anahtar

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>

Politika, anahtarı içeren herhangi bir değişkene referans verebilir. Bu örnekteki politika, requestAPIKey.key adlı bir değişkenden API anahtarını çıkarır.

Bu değişkenin nasıl doldurulacağı size bağlıdır. Örneğin, aşağıdaki örnekte gösterildiği gibi, myKey adlı bir sorgu parametresinden requestAPIKey.key değerini doldurmak için Değişkenleri Ayıkla politikasını kullanabilirsiniz:

<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar">
    <Source>request</Source>
    <QueryParam name="myKey">
        <Pattern ignoreCase="true">{key}</Pattern>
    </QueryParam>
    <VariablePrefix>requestAPIKey</VariablePrefix>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Erişim politikası akışı değişkenleri

<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars">
    <AssignVariable>
        <Name>devFirstName</Name>
        <Ref>verifyapikey.verify-api-key.developer.firstName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devLastName</Name>
        <Ref>verifyapikey.verify-api-key.developer.lastName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devEmail</Name>
        <Ref>verifyapikey.verify-api-key.developer.email</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Edge, geçerli bir API anahtarı için API anahtarını doğrulama politikasını yürütürken bir dizi akış değişkenini otomatik olarak doldurur. Bu değişkenleri kullanarak uygulama adı, uygulama kimliği ve uygulamayı kaydeden geliştirici veya şirketle ilgili bilgilere erişebilirsiniz. Yukarıdaki örnekte, API anahtarı doğrulandıktan sonra geliştiricinin adını, soyadını ve e-posta adresini almak için Mesaj Atama politikasını kullanıyorsunuz.

Bu değişkenlerin tümünün önünde şu önek bulunur:

verifyapikey.{policy_name}

Bu örnekte, API anahtarını doğrulama politikası adı "verify-api-key"dir. Bu nedenle, verifyapikey.verify-api-key.developer.firstName. değişkenine erişerek isteği yapan geliştiricinin adını referans olarak kullanırsınız.

Edge'i öğrenin

API anahtarını doğrulama politikası hakkında

Bir geliştirici Edge'e uygulama kaydettiğinde Edge otomatik olarak bir tüketici anahtarı ve gizli anahtar çifti oluşturur. Uygulamanın tüketici anahtarı ve gizli çiftini Edge kullanıcı arayüzünde görebilir veya Edge API'den erişebilirsiniz.

Uygulama kaydı sırasında geliştirici, uygulamayla ilişkilendirmek için bir veya daha fazla API ürünü seçer. API ürünü, API proxy'leri aracılığıyla erişilebilen bir kaynak koleksiyonudur. Ardından geliştirici, API anahtarını (tüketici anahtarı) uygulamayla ilişkili bir API ürünündeki API'ye yapılan her isteğin bir parçası olarak iletir. Daha fazla bilgi için Yayınlamaya genel bakış başlıklı makaleyi inceleyin.

API anahtarları, kimlik doğrulama jetonları olarak veya OAuth erişim jetonları almak için kullanılabilir. OAuth'ta API anahtarları "istemci kimliği" olarak adlandırılır. Bu adlar birbirinin yerine kullanılabilir. Daha fazla bilgi için OAuth ana sayfası'na bakın.

Edge, API anahtarını doğrulama politikası yürütülürken bir dizi akış değişkenini otomatik olarak doldurur. Daha fazla bilgi için aşağıdaki Akış değişkenleri bölümüne bakın.

Öğe Referansı

Bu politikada yapılandırabileceğiniz öğeler ve özellikler aşağıda verilmiştir:

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <APIKey ref="variable_containing_api_key"/>
</VerifyAPIKey>

<VerifyAPIKey> özellikleri

Aşağıdaki örnekte <VerifyAPIKey> etiketindeki özellikler gösterilmektedir:

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">

Aşağıdaki tabloda tüm politika üst öğelerinde ortak olan özellikler açıklanmaktadır:

Özellik Açıklama Varsayılan Varlık
name

Politikanın dahili adı. name özelliğinin değeri Harf, sayı, boşluk, kısa çizgi, alt çizgi ve nokta içermelidir. Bu değer, 255 karakteri aşmalıdır.

İsteğe bağlı olarak, politikayı<DisplayName> yönetim arayüzü proxy düzenleyicisinde farklı bir doğal dil adı kullanabilir.

 Yok Zorunlu
continueOnError

Bir politika başarısız olduğunda hata döndürmesi için false olarak ayarlayın. Bu beklenen bir durumdur çoğu politika için geçerli olur.

Akış yürütmenin bir politikadan sonra bile devam etmesi için true olarak ayarlayın başarısız olur.

 false İsteğe bağlı
enabled

Politikayı uygulamak için true olarak ayarlayın.

Politikayı devre dışı bırakmak için false değerine ayarlayın. Bu politika, bir akışa bağlı kalsa bile uygulanır.

 true İsteğe bağlı
async

Bu özelliğin desteği sonlandırıldı.

 false Kullanımdan kaldırıldı

&lt;DisplayName&gt; öğe

Politikayı name özelliğine ek olarak farklı bir doğal dil adına sahip yönetim arayüzü proxy düzenleyicisi.

<DisplayName>Policy Display Name</DisplayName>
Varsayılan

Yok

Bu öğeyi çıkarırsanız politikanın name özelliğinin değeri: kullanılır.
Varlık İsteğe bağlı
Tür Dize

<APIKey> öğesi

Bu öğe, API anahtarını içeren akış değişkenini belirtir. Genellikle istemci, API anahtarını bir sorgu parametresinde, HTTP üstbilgisinde veya form parametresinde gönderir. Örneğin, anahtar x-apikey adlı bir üstbilgide gönderilirse anahtar şu değişkende bulunur: request.header.x-apikey

Varsayılan Yok
Varlık Zorunlu
Tür Dize

Özellikler

Aşağıdaki tabloda <APIKey> öğesinin özellikleri açıklanmaktadır.

Özellik Açıklama Varsayılan Varlık
ref

API anahtarını içeren değişkene yapılan referans. Politika başına yalnızca bir konuma izin verilir.

 Yok Zorunlu

Örnekler

Bu örneklerde anahtar, parametreler ve x-apikey adlı bir başlıkta iletilir.

Sorgu parametresi olarak:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.x-apikey"/>
</VerifyAPIKey>

HTTP üstbilgisi olarak:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey"/>
</VerifyAPIKey>

HTTP formu parametresi olarak:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.formparam.x-apikey"/>
</VerifyAPIKey>

Şemalar

Akış değişkenleri

Geçerli bir API anahtarı üzerinde API anahtarını doğrulama politikası uygulandığında Edge, bir dizi akış değişkenini doldurur. Bu değişkenler, akışta daha sonra yürütülen politikalarda veya kodlarda kullanılabilir. Genellikle, API anahtarının özelliklerine (ör. uygulama adı, anahtarı yetkilendirmek için kullanılan API ürünü veya API anahtarının özel özellikleri) göre özel işleme gerçekleştirmek için kullanılır.

Politika, aşağıdakiler de dahil olmak üzere çeşitli akış değişkeni türlerini doldurur:

  • Genel
  • Uygulama
  • Geliştirici
  • Şirket
  • Analiz

Her akış değişkeni türünün farklı bir öneki vardır. Diziler olarak belirtilenler hariç tüm değişkenler skalerdir.

Genel akış değişkenleri

Aşağıdaki tabloda, API anahtarını doğrulama politikası tarafından doldurulan genel akış değişkenleri listelenmiştir. Bu değişkenlerin tümünün önünde şu önek bulunur:

verifyapikey.{policy_name}

Örneğin: verifyapikey.{policy_name}.client_id

Kullanılabilir değişkenler şunlardır:

Değişken Açıklama
client_id İstekte bulunan uygulama tarafından sağlanan tüketici anahtarı (API anahtarı veya uygulama anahtarı olarak da bilinir).
client_secret Tüketici anahtarıyla ilişkili tüketici gizli bilgisi.
redirection_uris İstekteki tüm yönlendirme URI'leri.
developer.app.id

İsteği gönderen geliştirici uygulamasının kimliği.
developer.app.name İsteği gönderen geliştirici uygulamasının uygulama adı.
developer.id

İstenen uygulamanın sahibi olarak kayıtlı geliştiricinin kimliği.
developer.{custom_attrib_name} Uygulama anahtarı profilinden türetilen tüm özel özellikler
DisplayName Politikanın <DisplayName> özelliğinin değeri.
failed API anahtarı doğrulama başarısız olduğunda "true" olarak ayarlanır.
{custom_app_attrib}

Uygulama profilinden türetilen tüm özel özellikler. Özel özelliğin adını belirtin.
apiproduct.name* İsteği doğrulamak için kullanılan API ürününün adı.
apiproduct.{custom_attrib_name}* API ürün profilinden türetilen tüm özel özellikler.
apiproduct.developer.quota.limit* API ürününde belirlenen kota sınırı (varsa).
apiproduct.developer.quota.interval* API ürününde belirlenen kota aralığı (varsa).
apiproduct.developer.quota.timeunit* API ürününde ayarlanan kota zaman birimi (varsa).
* API ürünleri geçerli ortam, proxy ve kaynaklarla (proxy.pathsuffix'dan türetilir) yapılandırılmışsa API ürün değişkenleri otomatik olarak doldurulur. API ürünlerini ayarlama talimatları için API'leri yayınlamak üzere Edge yönetim API'sini kullanma başlıklı makaleyi inceleyin.

Uygulama akışı değişkenleri

Uygulama hakkında bilgi içeren aşağıdaki akış değişkenleri politika tarafından doldurulur. Bu değişkenlerin tümünün önünde şu önek bulunur:

verifyapikey.{policy_name}.app.

Örneğin:

verifyapikey.{policy_name}.app.name

Kullanılabilir değişkenler şunlardır:

Değişken Açıklama
name Uygulamanın adı.
id Uygulamanın kimliği.
accessType Apigee tarafından kullanılmaz.
callbackUrl Uygulamanın geri çağırma URL'si. Genellikle yalnızca OAuth için kullanılır.
DisplayName Uygulamanın görünen adı.
status Uygulama durumu (ör. "onaylandı" veya "iptal edildi").
apiproducts Uygulamayla ilişkili API ürünlerinin listesini içeren bir dizi.
appFamily Uygulamayı içeren tüm uygulama aileleri veya "varsayılan".
appParentStatus Uygulamanın üst öğesinin durumu (ör. "etkin" veya "etkin değil")
appType Uygulama türü "Şirket" veya "Geliştirici" olarak.
appParentId Üst uygulamanın kimliği.
created_at Uygulamanın oluşturulduğu tarih/saat damgası.
created_by Uygulamayı oluşturan geliştiricinin e-posta adresi.
last_modified_at Uygulamanın en son güncellendiği tarih/saat damgası.
last_modified_by Uygulamayı en son güncelleyen geliştiricinin e-posta adresi.
{app_custom_attributes} Herhangi bir özel uygulama özelliği. Özel özelliğin adını belirtin.

Geliştirici akışı değişkenleri

Geliştirici hakkında bilgi içeren aşağıdaki akış değişkenleri, politika tarafından doldurulur. Bu değişkenlerin tümünün önünde şu önek bulunur:

verifyapikey.{policy_name}.developer

Örneğin:

verifyapikey.{policy_name}.developer.id

Kullanılabilir değişkenler şunlardır:

Değişken Açıklama
id {org_name}@@@{developer_id} değerini döndürür.
userName Geliştiricinin kullanıcı adı.
firstName Geliştiricinin adı.
lastName Geliştiricinin soyadı.
email Geliştiricinin e-posta adresi.
status Geliştiricinin durumu (etkin, etkin değil veya login_lock).
apps Geliştiriciyle ilişkili uygulamaların dizisi.
created_at Geliştiricinin oluşturulduğu tarih/saat damgası.
created_by Geliştiriciyi oluşturan kullanıcının e-posta adresi.
last_modified_at Geliştiricinin en son değiştirildiği tarih/saat damgası.
last_modified_by Geliştiriciyi değiştiren kullanıcının e-posta adresi.
{developer_custom_attributes} Tüm özel geliştirici özellikleri. Özel özelliğin adını belirtin.
Company Geliştiriciyle ilişkili bir şirket varsa bu şirketin adı.

Şirket akışı değişkenleri

Şirket hakkında bilgi içeren aşağıdaki akış değişkenleri politika tarafından doldurulur. Bu değişkenlerin tümünün önünde şu önek bulunur:

verifyapikey.{policy_name}.company

Örneğin:

verifyapikey.{policy_name}.company.name

Kullanılabilir değişkenler şunlardır:

Değişken Açıklama
name Şirket adı.
displayName Şirketin görünen adı.
id

Şirket kimliği.
apps Şirket uygulamalarının listesini içeren bir dizi.
appOwnerStatus
Uygulama sahibinin durumu (etkin, etkin değil veya login_lock).
created_at Şirketin oluşturulduğu tarih/saat damgası.
created_by Şirketi oluşturan kullanıcının e-posta adresi.
last_modified_at Şirketin en son değiştirildiği tarih/saat damgası.
last_modified_by Şirketi en son değiştiren kullanıcının e-posta adresi.
{company_custom_attributes} Herhangi bir özel şirket özelliği. Özel özelliğin adını belirtin.

Analytics değişkenleri

Geçerli bir API anahtarı için API anahtarını doğrulama politikası uygulandığında Analytics'te aşağıdaki değişkenler otomatik olarak doldurulur. Bu değişkenler yalnızca API anahtarını doğrulama politikası ve OAuth politikalarıyla doldurulur.

Değişkenler ve değerler, geliştiriciler ve uygulamalar tarafından tüketim kalıpları hakkında görünürlük elde etmek için Analytics raporları oluşturmada boyut olarak kullanılabilir.

  • apiproduct.name
  • developer.app.name
  • client_id
  • developer.id

Hata referansı

Bu bölümde, bu politika bir hatayı tetiklediğinde döndürülen hata kodları ve hata mesajlarının yanı sıra Edge tarafından ayarlanan hata değişkenleri açıklanmaktadır. Hata kuralları geliştirirken bu bilgilerin farkında olmanız önemlidir. hoşuma gitmesi için bir fırsattır. Daha fazla bilgi için Bilmeniz gerekenler Politika hataları ve Kullanım sorun.

Çalışma zamanı hataları

Bu hatalar, politika yürütüldüğünde ortaya çıkabilir.

Hata kodu HTTP durumu Neden
keymanagement.service.CompanyStatusNotActive 401 Geliştirici Uygulaması ile ilişkilendirilmiş ve kullandığınız API anahtarına sahip Şirket'in bir etkin değil durumu. Bir Şirketin durumu etkin değil olarak ayarlandığında, ilgili Şirket ile ilişkili geliştiriciler veya uygulamalardır. Bir kuruluş yöneticisi Şirketin durumunu değiştirebilir yönetim API'sini kullanarak. Durumu Ayarlama bir şirkettir.
keymanagement.service.DeveloperStatusNotActive 401

Kullandığınız API anahtarına sahip geliştirici uygulamasını oluşturan geliştirici, etkin değil. Uygulama Geliştirici'nin durumu etkin değil olarak ayarlandığında, tüm Geliştirici Uygulamaları otomatik olarak devre dışı bırakılır. Uygun izinlere sahip bir yönetici kullanıcı (Kuruluş Yöneticisi gibi) bir geliştiricinin durumunu aşağıdaki konumlarda değiştirebilir: yöntemler:
keymanagement.service.invalid_client-app_not_approved 401 API anahtarıyla ilişkilendirilmiş Geliştirici Uygulaması iptal edildi. İptal edilen bir uygulama API ürünlerine erişemez ve Apigee Edge tarafından yönetilen hiçbir API'yi çağıramaz. Kuruluş yöneticisi şunları yapabilir: yönetim API'sini kullanarak bir geliştirici uygulamasının durumunu değiştirme Bkz. Geliştirici Uygulamasını Onaylayın veya İptal Edin.
oauth.v2.FailedToResolveAPIKey 401 Politika, API anahtarını politikanın &lt;APIKey&gt; öğesi. Bu hata, değişkeni mevcut değil (çözümlenemiyor).
oauth.v2.InvalidApiKey 401 Edge, bir API anahtarını aldı ancak bu anahtar geçersiz. Edge, anahtarı içinde arattığında istekte gönderilenle tam olarak eşleşmelidir. API işe yaradıysa anahtarın yeniden oluşturulmadığından emin olun. Anahtar yeniden oluşturulduysa eski anahtarı kullanmaya çalışırsanız bu hatayı alabilirsiniz. Ayrıntılar için Uygulamaları kaydetme ve API'yi yönetme tuşlar.
oauth.v2.InvalidApiKeyForGivenResource 401 Edge, bir API anahtarını aldı ve bu anahtar geçerliydi; ancak, Geliştirici Uygulaması'nda bir Ürün üzerinden API proxy'nizle ilişkili onaylanmış anahtar.

Dağıtım hataları

Bu politikayı içeren bir proxy dağıttığınızda bu hatalar oluşabilir.

Hata adı Neden
SpecifyValueOrRefApiKey <APIKey> öğesinde değer veya anahtar belirtilmemiş.

Hata değişkenleri

Bu değişkenler, çalışma zamanı hatası oluştuğunda ayarlanır. Daha fazla bilgi için Bilmeniz gerekenler hakkında daha fazla bilgi edinin.

Değişkenler Konum Örnek
fault.name="fault_name" fault_name, yukarıdaki Çalışma zamanı hataları tablosunda listelendiği gibi hatanın adıdır. Hata adı, hata kodunun son kısmıdır. fault.name Matches "FailedToResolveAPIKey"
oauthV2.policy_name.failed policy_name, hataya neden olan politikanın kullanıcı tarafından belirtilen adıdır. oauthV2.VK-VerifyAPIKey.failed = true

Örnek hata yanıtları

{  
   "fault":{  
      "faultstring":"Invalid ApiKey",
      "detail":{  
         "errorcode":"oauth.v2.InvalidApiKey"
      }
   }
}
 
{  
   "fault":{  
      "detail":{  
         "errorcode":"keymanagement.service.DeveloperStatusNotActive"
      },
      "faultstring":"Developer Status is not Active"
   }
}

Örnek hata kuralı

<FaultRule name="FailedToResolveAPIKey">
    <Step>
        <Name>AM-FailedToResolveAPIKey</Name>
    </Step>
    <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition>
</FaultRule>

İlgili konular