Zasady dotyczące objaśnienia Java

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

Co

Umożliwia korzystanie z Javy do implementowania niestandardowego zachowania, które nie jest dostępne natychmiast przez zasady Apigee. W kodzie w Javie masz dostęp do właściwości wiadomości (nagłówków, parametrów zapytania, treści) i zmiennych przepływu w procesie serwera proxy. Jeśli dopiero zaczynasz korzystać z tych zasad, dowiedz się, jak utworzyć objaśnienie w Javie.

Informacje o obsługiwanych wersjach Javy znajdziesz w sekcji Obsługiwane oprogramowanie i obsługiwane wersje.

Kiedy

Wskazówki znajdziesz w sekcji „Kiedy należy użyć objaśnienia w Javie?” w artykule Jak utworzyć objaśnienie w Javie.

Informacje

Zasada objaśnień w Javie pozwala m.in. pobierać i ustawiać zmienne przepływu, wykonywać niestandardowe logiki, obsługiwać błędy, wyodrębniać dane z żądań lub odpowiedzi. Ta zasada umożliwia wdrożenie niestandardowego zachowania, którego nie obejmują żadne inne standardowe zasady brzegowe.

Aplikację w Javie możesz spakować z dowolnymi plikami JAR w pakiecie. Pamiętaj, że obowiązują pewne ograniczenia związane z objaśnieniami w języku Java. Ich listę znajdziesz w sekcji Ograniczenia.

Sample

Prosty przykład

Jak utworzyć objaśnienie w Javie

Pobieranie właściwości w kodzie Java

Element <Property> zasady pozwala określić w kodzie Javy parę nazwa/wartość, którą można pobierać w czasie działania. Przykładowy działający przykład z użyciem właściwości znajdziesz w sekcji Jak używać właściwości w objaśnieniu Java.

Użyj atrybutu name elementu <Property>, aby określić nazwę, za pomocą której chcesz uzyskać dostęp do właściwości z kodu Java. Wartość elementu <Property> (wartość między tagiem otwierającym i zamykającym) to wartość, którą otrzyma kod Java. Wartość musi być ciągiem znaków. Nie można się odwoływać do zmiennej przepływu, aby ją pobrać.

  • Skonfiguruj usługę. W tym przypadku wartością właściwości jest nazwa zmiennej response.status.code.
    <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
        <DisplayName>JavaCallout</DisplayName>
        <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
        <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
        <Properties>
            <Property name="source">response.status.code</Property>
        </Properties>
    </Javascript>
    
  • W swoim kodzie Java zaimplementuj ten konstruktor w implementacji klasy Execution w ten sposób:
    public class MyJavaCallout implements Execution{
        public MyJavaCallout(Map<string, string> props){
            
                // Extract property values from map.
        }
        ...
    }
    

Ustawianie zmiennych przepływu w kodzie Java

Jasny opis ustawiania zmiennych w kontekście wiadomości (zmiennych przepływu) w kodzie Java znajdziesz w tym poście w społeczności Apigee.


Odwołanie do elementu

Dokumentacja elementu opisuje elementy i atrybuty zasady JavaCallout.

<JavaCallout name="MyJavaCalloutPolicy">
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
</JavaCallout>

Atrybuty <JavaCallout>

<JavaCallout name="MyJavaCalloutPolicy" enabled="true" continueOnError="false" async="false" >

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

Atrybut Opis Domyślne Obecność
name

Wewnętrzna nazwa zasady. Wartość atrybutu name może zawierać litery, cyfry, spacje, łączniki, podkreślenia i kropki. Ta wartość nie może przekraczać 255 znaków.

Opcjonalnie możesz użyć elementu <DisplayName>, aby oznaczyć zasadę w edytorze serwera proxy interfejsu zarządzania inną nazwą w języku naturalnym.

Nie dotyczy Wymagane
continueOnError

Ustaw wartość false, aby zwracać błąd w przypadku niepowodzenia zasady. Jest to normalne działanie większości zasad.

Ustaw jako true, aby wykonywanie przepływu było kontynuowane nawet po awarii zasady.

false Opcjonalnie
enabled

Ustaw jako true, aby wymuszać zasadę.

Ustaw wartość false, aby wyłączyć tę zasadę. Zasada nie będzie egzekwowana, nawet jeśli pozostanie dołączona do procesu.

prawda Opcjonalnie
async

Ten atrybut został wycofany.

false Wycofano

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>
Domyślne

Nie dotyczy

Jeśli pominiesz ten element, zostanie użyta wartość atrybutu name zasady.

Obecność Opcjonalnie
Typ Ciąg znaków

Element <ClassName>

Określa nazwę klasy Java, która jest wykonywana po uruchomieniu zasady objaśnień Java. Klasa musi być zawarta w pliku JAR określonym przez <ResourceURL>. Zobacz też, jak utworzyć objaśnienie w języku Java.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Domyślnie: Nie dotyczy
Obecność: Wymagane
Typ: Ciąg znaków

Element <Property>

Wskazuje właściwość, do której można uzyskać dostęp w kodzie Java w czasie działania. W przypadku każdej właściwości musisz określić literałową wartość ciągu. W tym elemencie nie możesz się odwoływać do zmiennych przepływu. Przykładowy działający przykład z użyciem właściwości znajdziesz w sekcji Jak używać właściwości w objaśnieniu Java.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
Domyślnie: Brak
Obecność: Opcjonalnie
Typ: Ciąg znaków

Atrybuty

Atrybut Opis Domyślne Obecność
nazwa

Określa nazwę właściwości.

Nie dotyczy To pole jest wymagane.

<ResourceURL>

Ten element określa plik JAR Javy, który jest wykonywany po uruchomieniu zasady objaśnienia w Javie.

Możesz zapisać ten plik w zakresie serwera proxy interfejsu API (w sekcji /apiproxy/resources/java w pakiecie proxy interfejsu API lub w sekcji Skrypty w panelu nawigacji edytora proxy interfejsu API) albo w zakresach organizacji lub środowiska do ponownego użycia w wielu serwerach proxy interfejsu API, jak opisano w plikach zasobów.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Domyślnie: Brak
Obecność: Wymagane
Typ: Ciąg znaków

Informacje o błędach

W tej sekcji opisujemy kody błędów i komunikaty o błędach, które są zwracane, oraz zmienne błędów ustawiane przez Edge, gdy ta zasada wywołuje błąd. Te informacje są ważne, jeśli opracowujesz reguły dotyczące błędów do obsługi takich błędów. Więcej informacji znajdziesz w sekcjach Co musisz wiedzieć o błędach zasad i Postępowanie w przypadku błędów.

Błędy w czasie wykonywania

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

Kod błędu Stan HTTP Przyczyna Napraw
steps.javacallout.ExecutionError 500 Występuje, gdy kod Java zgłasza wyjątek lub zwraca wartość null podczas wykonywania zasady JavaCallout.

Błędy wdrażania

Te błędy mogą wystąpić po wdrożeniu serwera proxy zawierającego zasadę.

Nazwa błędu Ciąg błędu Stan HTTP Występuje, gdy
ResourceDoesNotExist Resource with name [name] and type [type] does not exist Nie dotyczy Plik określony w elemencie <ResourceURL> nie istnieje.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] Nie dotyczy Pliku klasy określonego w elemencie <ClassName> nie ma w pliku jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] Nie dotyczy Zobacz ciąg błędu. Zobacz też obsługiwane i obsługiwane wersje oprogramowania.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] Nie dotyczy Zobacz ciąg błędu.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] Nie dotyczy Zobacz ciąg błędu.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] Nie dotyczy Zobacz ciąg błędu.
NoResourceForURL Could not locate a resource with URL [string] Nie dotyczy Zobacz ciąg błędu.

Zmienne błędów

Te zmienne są ustawiane, gdy zasada wywołuje błąd. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach związanych z naruszeniem zasad.

Zmienne Gdzie Przykład
fault.name="fault_name" fault_name to nazwa błędu podana w tabeli Błędy środowiska wykonawczego powyżej. Nazwa błędu to ostatnia część kodu. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name to określona przez użytkownika nazwa zasady, która spowodowała błąd. javacallout.JC-GetUserData.failed = true

Przykładowa odpowiedź na błąd

{  
   "fault":{  
      "faultstring":"Failed to execute JavaCallout. [policy_name]",
      "detail":{  
         "errorcode":"javacallout.ExecutionError"
      }
   }
}

Przykładowa reguła błędu

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

Schematy

Kompilowanie i wdrażanie

Szczegółowe informacje o tym, jak skompilować niestandardowy kod Java i wdrożyć go z użyciem serwera proxy, znajdziesz w sekcji Jak utworzyć objaśnienie w Javie.

Ograniczenia

Poniżej znajdziesz ograniczenia, które musisz wziąć pod uwagę podczas tworzenia objaśnień w języku Java:

  • Większość wywołań systemowych jest zabroniona. Nie możesz na przykład dokonywać odczytów ani zapisów w wewnętrznym systemie plików.
  • Dostęp do sieci za pomocą gniazd. Apigee ogranicza dostęp do adresów sitelocal, Anylocal, loopback i linklocal.
  • Objaśnienie nie może pobrać informacji o bieżącym procesie, liście procesów ani wykorzystaniu procesora/pamięci na komputerze. Chociaż niektóre z takich wywołań mogą działać, nie są obsługiwane i w każdej chwili mogą zostać aktywnie wyłączone. Aby zapewnić zgodność w przyszłości, unikaj wykonywania takich wywołań w kodzie.
  • Zależność od bibliotek Javy zawartych w Apigee Edge nie jest obsługiwana. Te biblioteki służą tylko do obsługi funkcji usługi Edge i nie ma gwarancji, że biblioteka będzie dostępna od nowych wersji do publikacji.
  • Nie używaj io.apigee ani com.apigee jako nazw pakietów w objaśnieniach Java. Te nazwy są zarezerwowane i używane przez inne moduły Apigee.

Sposób prezentacji

Umieść plik JAR na serwerze proxy interfejsu API w lokalizacji /resources/java. Jeśli objaśnienie w Javie korzysta z dodatkowych bibliotek zewnętrznych w pakiecie jako niezależne pliki JAR, umieść te pliki JAR w katalogu /resources/java także, aby mieć pewność, że zostaną prawidłowo wczytane w czasie działania.

Jeśli do tworzenia lub modyfikowania serwera proxy używasz interfejsu zarządzania, dodaj nowy zasób i określ dodatkowy zależny plik JAR. Jeśli jest wiele plików JAR, po prostu dodaj je jako zasoby dodatkowe. Nie musisz modyfikować konfiguracji zasad, aby odwoływać się do dodatkowych plików JAR. Wystarczy umieścić je w grupie /resources/java.

Informacje na temat przesyłania plików JAR w Javie znajdziesz w artykule Pliki zasobów.

Szczegółowy przykład ilustrujący, jak spakować i wdrożyć objaśnienie w Javie za pomocą Maven lub javac, znajdziesz w artykule o tworzeniu objaśnienia w Javie.

dokument Javadoc,

Dokument Javadoc do napisania kodu objaśnienia w Javie znajdziesz tutaj na GitHubie. Musisz skopiować lub pobrać kod HTML do swojego systemu, a potem po prostu otworzyć plik index.html w przeglądarce.

Zastosowanie

  • Zasada dotycząca objaśnień w języku Java nie zawiera rzeczywistego kodu. Zamiast tego zasada objaśnienia w języku Java odwołuje się do „zasobu” języka Java i określa krok w przepływie interfejsu API, w którym jest wykonywany kod w Javie. Możesz przesłać plik Java JAR za pomocą edytora proxy interfejsu zarządzania lub dodać go do katalogu /resources/java na serwerach proxy interfejsu API tworzonych lokalnie.
  • W przypadku lekkich operacji, takich jak wywołania interfejsu API do usług zdalnych, zalecamy stosowanie zasady ServiceCallout. Zapoznaj się z zasadami dotyczącymi objaśnień usługi.
  • W przypadku stosunkowo prostych interakcji z treścią wiadomości, takich jak modyfikowanie lub wyodrębnianie nagłówków, parametrów lub treści wiadomości, Apigee zaleca użycie zasady JavaScript.

Powiązane artykuły