Zasady dotyczące objaśnień w rozszerzeniach

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

Użyj zasady ExtensionCallout, aby dodać rozszerzenie do serwera proxy interfejsu API.

Rozszerzenie zapewnia dostęp do określonego zasobu spoza Apigee Edge. Zasobem mogą być usługi Google Cloud Platform, takie jak Cloud Storage czy Cloud Speech-to-Text. Zasóbem może być jednak dowolny zewnętrzny zasób dostępny przez HTTP lub HTTPS.

Omówienie rozszerzeń znajdziesz w artykule Co to są rozszerzenia? Samouczek dla początkujących znajdziesz na stronie Samouczek: dodawanie rozszerzeń i korzystanie z nich.

Zanim uzyskasz dostęp do rozszerzenia z poziomu zasady ExtensionCallout, musisz je dodać, skonfigurować i wdrożyć z pakietu rozszerzeń, który jest już zainstalowany w organizacji Apigee Edge.

Sample

Poniżej znajdziesz przykładową zasadę do wykorzystania z rozszerzeniem Cloud Logging:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Logging-Extension">
        <DisplayName>Logging Extension</DisplayName>
        <Connector>cloud-extension-sample</Connector>
        <Action>log</Action>
        <Input>{
                "logName" : "example-log",
                "metadata" : "test-metadata",
                "message" : "This is a test"
        }</Input>
    <Output>cloud-extension-example-log</Output>
</ConnectorCallout>

Pełny samouczek dotyczący rozszerzenia Cloud Logging zawiera Samouczek: korzystanie z rozszerzeń.

Przykłady wszystkich dostępnych rozszerzeń znajdziesz w artykule Omówienie rozszerzeń.

Zasady dotyczące rozszerzenia ExtensionCallout

Użyj zasady ExtensionCallout, jeśli chcesz użyć skonfigurowanego rozszerzenia, aby uzyskać dostęp do zasobu zewnętrznego przez serwer proxy interfejsu API.

Aby korzystać z tej zasady, musisz mieć:

• Kilka informacji o zasobie zewnętrznym, do którego chcesz uzyskać dostęp za pomocą tej zasady. Dane te będą dotyczyć konkretnego zasobu. Jeśli na przykład zasada będzie miała dostęp do bazy danych Cloud Firestore, musisz znać kolekcję i nazwę dokumentu, które chcesz utworzyć lub do którego chcesz uzyskać dostęp. Zazwyczaj podczas konfigurowania obsługi żądań i odpowiedzi w tej zasadzie użyjesz informacji dotyczących konkretnego zasobu.
• Rozszerzenie dodane, skonfigurowane i wdrożone w środowisku, w którym zostanie wdrożony serwer proxy interfejsu API. Inaczej mówiąc, jeśli chcesz użyć tej zasady, aby uzyskać dostęp do konkretnej usługi Google Cloud, w Twoim środowisku musi istnieć wdrożone rozszerzenie tej usługi. Szczegóły konfiguracji zwykle zawierają informacje wymagane do ograniczenia dostępu do zasobu, np. identyfikator projektu lub nazwę konta.

Korzystanie z zasady ExtensionCallout w obrębie PostClientFlow

Zasadę ExtensionCallout możesz wywołać z obiektu PostClientFlow serwera proxy interfejsu API. Obiekt PostClientFlow jest uruchamiany po wysłaniu odpowiedzi do klienta wysyłającego żądanie, dzięki czemu wszystkie wskaźniki są dostępne do logowania. Szczegółowe informacje o korzystaniu z PostClientFlow znajdziesz w dokumentacji konfiguracji serwera proxy interfejsu API.

Jeśli chcesz używać zasady ExtensionCallout, aby wywoływać rozszerzenie Google Cloud Logging z poziomu PostClientFlow, upewnij się, że flaga features.allowExtensionsInPostClientFlow jest ustawiona na true w Twojej organizacji.

• Jeśli korzystasz z Apigee Edge dla Public Cloud, flaga features.allowExtensionsInPostClientFlow jest domyślnie ustawiona na true.

• Jeśli korzystasz z Apigee Edge dla Private Cloud, użyj interfejsu API Aktualizowanie właściwości organizacji, aby ustawić flagę features.allowExtensionsInPostClientFlow na true.

Wszystkie ograniczenia dotyczące wywoływania zasady MessageLogging z poziomu PostClientFlow mają też zastosowanie do zasady ExtensionCallout. Więcej informacji znajdziesz w uwagach o użytkowaniu.

Odwołanie do elementu

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Extension-Callout-1">
    <DisplayName/>
    <Connector/>
    <Action/>
    <Input/>
    <Output/>
</ConnectorCallout>

Atrybuty <ConnectorCallout>

<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">

Tabela poniżej zawiera opis atrybutów wspólnych dla wszystkich elementów nadrzędnych zasad:

Element <DisplayName>

Użyj oprócz atrybutu name, aby oznaczyć zasadę w edytorze serwera proxy interfejsu zarządzania inną nazwą w języku naturalnym.

<DisplayName>Policy Display Name</DisplayName>

Element <Action>

Działanie ujawnione przez rozszerzenie, które powinna zostać wywołana przez zasadę.

<Action>action-exposed-by-extension</Action>

Każde rozszerzenie ujawnia własny zestaw działań zapewniających dostęp do funkcji zasobu reprezentowanego przez rozszerzenie. Działanie można traktować jako funkcję wywoływaną przy użyciu tej zasady przy użyciu zawartości elementu <Input> do określania argumentów funkcji. Odpowiedź działania jest przechowywana w zmiennej określonej w elemencie <Output>.

Listę funkcji rozszerzenia znajdziesz w dokumentacji rozszerzenia wywoływanego z poziomu tej zasady.

Element <Connector>

Nazwa skonfigurowanego rozszerzenia, którego chcesz użyć. Jest to nazwa ograniczona do środowiska nadana rozszerzeniu, gdy zostało ono skonfigurowane na potrzeby wdrożenia w środowisku.

<Connector>name-of-configured-extension</Connector>

Wartości konfiguracji rozszerzenia mogą się różnić od wartości innego wdrożonego rozszerzenia opartego na tym samym pakiecie rozszerzeń. Te wartości konfiguracyjne mogą odzwierciedlać istotne różnice w działaniu środowiska wykonawczego między rozszerzeniami skonfigurowanymi w tym samym pakiecie. Pamiętaj więc, by wybrać prawidłowe rozszerzenie do wywołania.

Element <Input>

Plik JSON zawierający treść żądania, która ma zostać wysłana do rozszerzenia.

<Input><![CDATA[ JSON-containing-input-values ]]></Input>

Jest to argument dotyczący działania określonego w elemencie <Action>. Wartość elementu <Input> różni się w zależności od wywoływanego rozszerzenia i czynności. Szczegółowe informacje o właściwościach poszczególnych działań znajdziesz w dokumentacji pakietu rozszerzeń.

Pamiętaj, że chociaż wiele wartości elementu <Input> będzie działać prawidłowo bez uwzględniania sekcji <![CDATA[]]>, reguły JSON dopuszczają wartości, które nie zostaną przetworzone jako XML. Zalecamy umieszczenie pliku JSON w sekcji CDATA, aby uniknąć błędów analizy w czasie działania.

Wartość elementu <Input> to poprawnie sformatowany plik JSON, którego właściwości określają wartości wysyłane do wywoływanego działania rozszerzenia. Na przykład działanie log rozszerzenia Google Cloud Logging pobiera wartości określające dziennik do zapisu (logName), metadane, które chcesz dołączyć do wpisu (metadata) oraz komunikat logu (data). Oto przykład:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "This is a test"
}]]></Input>

Treść <Input> jest traktowana jako szablon wiadomości. Oznacza to, że nazwa zmiennej ujęta w nawiasy klamrowe jest zastępowana w czasie działania wartością zmiennej, do której odwołuje się ta zmienna.

Możesz np. przepisać poprzedni blok <Input>, aby użyć zmiennej przepływu client.ip do pobrania adresu IP klienta wywołującego serwer proxy interfejsu API:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "{client.ip}"
}]]></Input>

Jeśli chcesz, aby wartość właściwości w pliku JSON była ujęta w cudzysłowach w czasie działania, pamiętaj, aby użyć cudzysłowów w kodzie JSON. Dzieje się tak nawet wtedy, gdy określisz zmienną przepływu jako wartość właściwości JSON, która ma być rozpoznawana w czasie działania.

Poniższy przykład <Input> zawiera 2 odwołania do zmiennych przepływu:

<Input><![CDATA[{
  "logName" : "example-log",
  "metadata" : {my.log.entry.metadata},
  "message" : "{client.ip}"
}]]></Input>

W czasie działania wartości właściwości JSON są rozpoznawane w ten sposób:

• Wartość właściwości logName – literał ciągu znaków example-log.
• Wartość właściwości metadata – wartość zmiennej przepływu my.log.entry.metadata bez cudzysłowów. Jest to przydatne, jeśli wartość zmiennej jest ustawiona w formacie JSON reprezentującym obiekt.
• Wartość właściwości message – wartość zmiennej przepływu client.ip z cudzysłowami.

Element <output>

Nazwa zmiennej, która przechowuje odpowiedź działania rozszerzenia.

<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->

lub

<Output parsed="false">variable-name</Output>  <!-- The JSON object inside the variable is raw, unparsed -->

Po otrzymaniu odpowiedzi wartość jest umieszczana w określonej tutaj zmiennej, skąd można uzyskać do niej dostęp za pomocą innego kodu serwera proxy interfejsu API.

Obiekty odpowiedzi rozszerzeń są w formacie JSON. Są 2 opcje obsługi plików JSON przez zasadę:

• Przeanalizowane (domyślnie): zasada analizuje obiekt JSON i automatycznie generuje zmienne z danymi JSON. Jeśli na przykład plik JSON zawiera zmienną "messageId" : 12345;, a zmienną wyjściową nazywasz extensionOutput, identyfikator tej wiadomości możesz uzyskać w innych zasadach, korzystając ze zmiennej {extensionOutput.messageId}.
• Nieprzeanalizowana: zmienna wyjściowa zawiera nieprzetworzoną, nieprzetworzoną odpowiedź JSON z rozszerzenia. (Możesz też przeanalizować wartość odpowiedzi w osobnym kroku, korzystając z zasad JavaScript).

Atrybuty <output>

Zmienne przepływu

Brak.

Kody błędów

Błędy zwracane z zasad Apigee Edge mają spójny format opisany w dokumentacji błędów zasad.

W tej sekcji znajdziesz komunikaty o błędach i zmienne przepływu, które są ustawiane, gdy zasada powoduje błąd. Ta informacja jest ważna, gdy opracowujesz reguły awarii serwera proxy. Aby dowiedzieć się więcej, przeczytaj artykuły Błędy w zasadach i Jak postępować w przypadku błędów.

Błędy w czasie wykonywania

Te błędy mogą wystąpić podczas wykonywania zasady.

Błędy wdrażania

Te błędy mogą wystąpić, gdy wdrażasz serwer proxy zawierający tę zasadę.