Zasady dotyczące objaśnienia Java

Wyświetlasz dokumentację Apigee Edge.
Przejdź do dokumentacji Apigee X. info

Co

Umożliwia używanie języka Java do implementowania niestandardowych działań, które nie są dostępne w standardowych zasadach Apigee. W kodzie Java możesz uzyskiwać dostęp do właściwości wiadomości (nagłówków, parametrów zapytania, treści) i zmiennych przepływu w przepływie proxy. Jeśli dopiero zaczynasz korzystać z tych zasad, przeczytaj artykuł Tworzenie wywołania Java callout.

Obsługiwane wersje języka Java znajdziesz w artykule Obsługiwane oprogramowanie i obsługiwane wersje.

Kiedy

Wskazówki znajdziesz w sekcji "Kiedy należy używać wywołania Java?" w artykule Tworzenie wywołania Java.

Informacje

Zasady wywołania Java umożliwiają pobieranie i ustawianie zmiennych przepływu, wykonywanie niestandardowej logiki i obsługę błędów, wyodrębnianie danych z żądań lub odpowiedzi i wiele innych. Te zasady pozwalają na implementowanie niestandardowych działań, które nie są objęte żadnymi innymi standardowymi zasadami Edge.

Aplikację Java możesz spakować z dowolnymi plikami JAR. Pamiętaj że istnieją pewne ograniczenia dotyczące tego, co możesz zrobić za pomocą wywołania Java. Są one wymienione poniżej w sekcji Ograniczenia.

Przykłady

Prosty przykład

Jak utworzyć wywołanie Java

Pobieranie właściwości w kodzie Java

Element <Property> zasad umożliwia określenie pary nazwa/wartość , którą można pobrać w czasie działania w kodzie Java. Działający przykład użycia właściwości znajdziesz w artykule Jak używać właściwości w wywołaniu Java.

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

  • Skonfiguruj właściwość. 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 kodzie Java zaimplementuj ten konstruktor w implementacji klasy Execution w następujący 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

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

Dokumentacja elementów

Dokumentacja elementów opisuje elementy i atrybuty zasad 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" >

W tej tabeli opisano atrybuty wspólne dla wszystkich elementów nadrzędnych zasad:

Atrybut Opis Domyślny 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> do oznaczenia zasady jako edytor proxy interfejsu zarządzania z inną nazwą w języku naturalnym.

 Nie dotyczy Wymagane
continueOnError

Ustaw jako false, aby w przypadku niepowodzenia zasady zwracany był błąd. To normalne w przypadku większości zasad.

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

 fałsz Opcjonalnie
enabled

Aby egzekwować zasadę, ustaw wartość true.

Aby wyłączyć zasadę, ustaw wartość false. Te zasady nie będą jest wymuszane nawet wtedy, gdy jest ono połączone z przepływem.

 prawda Opcjonalnie
async

Ten atrybut został wycofany.

 fałsz Wycofano

&lt;DisplayName&gt; element

Używaj oprócz atrybutu name do oznaczania zasady w edytor proxy interfejsu zarządzania z inną nazwą w języku naturalnym.

<DisplayName>Policy Display Name</DisplayName>
Domyślny

Nie dotyczy

Jeśli pominiesz ten element, atrybut name zasady otrzyma wartość .
Obecność Opcjonalnie
Typ Ciąg znaków

Element <ClassName>

Określa nazwę klasy Java, która jest wykonywana po uruchomieniu zasad wywołania Java. Klasa musi być zawarta w pliku JAR określonym przez element <ResourceURL>. Zobacz też Tworzenie wywołania Java callout.

<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>

Określa właściwość, do której można uzyskać dostęp z kodu Java w czasie działania. W przypadku każdej właściwości musisz określić wartość literału ciągu znaków. W tym elemencie nie możesz odwoływać się do zmiennych przepływu. Działający przykład użycia właściwości znajdziesz w artykule Jak używać właściwości w wywołaniu Java.

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

Atrybuty

Atrybut Opis Domyślny Obecność
nazwa

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

 Nie dotyczy Wymagane.

Element<ResourceURL>

Ten element określa plik JAR Java, który będzie wykonywany po uruchomieniu zasad wywołania Java.

Ten plik możesz przechowywać w zakresie proxy interfejsu API (w pakiecie proxy interfejsu API w katalogu /apiproxy/resources/java lub w sekcji Skrypty w panelu nawigacji edytora proxy interfejsu API) albo w zakresie organizacji lub środowiska, aby można go było używać w wielu proxy interfejsu API, jak opisano w sekcji Pliki 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

Odniesienie do błędów

W tej sekcji opisano kody błędów i komunikaty o błędach, które są zwracane, oraz zmienne błędów ustawiane przez Edge, gdy ta zasada wyzwala błąd. Warto o tym wiedzieć, jeśli rozwijasz reguły błędów, aby obsługi błędów. Więcej informacji znajdziesz w artykule Co musisz wiedzieć o błędach związanych z zasadami i postępowaniu z błędami

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 w Javie zgłasza wyjątek lub zwraca wartość null podczas wykonywania zasady JavaCallout.

Błędy wdrażania

Te błędy mogą wystąpić podczas wdrażania 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 sekcji jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] Nie dotyczy Zobacz ciąg błędu. Zobacz też Obsługiwane oprogramowania i obsługiwanych wersji.
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 ta zasada wywołuje błąd. Więcej informacji znajdziesz w artykule Podstawowe informacje 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 czasu działania powyżej. Nazwa błędu to ostatnia część kodu błędu. 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 za pomocą proxy, znajdziesz w artykule Tworzenie wywołania Java callout.

Ograniczenia

Poniżej znajdziesz ograniczenia, które musisz wziąć pod uwagę podczas pisania wywołań Java:

  • Większość wywołań systemowych jest niedozwolona. Nie możesz na przykład odczytywać ani zapisywać wewnętrznego systemu plików.
  • Dostęp do sieci przez gniazda. Apigee ogranicza dostęp do adresów sitelocal, anylocal, loopback i linklocal.
  • Wywołanie nie może uzyskać informacji o bieżącym procesie, liście procesów ani wykorzystaniu procesora/pamięci na maszynie. Chociaż niektóre z tych wywołań mogą działać, nie są one obsługiwane i mogą zostać w każdej chwili aktywnie wyłączone. Aby zapewnić zgodność z przyszłymi wersjami, unikaj wykonywania takich wywołań w kodzie.
  • Korzystanie z bibliotek Java, które są dołączone do Apigee Edge, nie jest obsługiwane. Te biblioteki służą tylko do obsługi funkcji Edge i nie ma gwarancji, że biblioteka będzie dostępna w kolejnych wersjach.
  • W wywołaniach Java nie używaj nazw pakietów io.apigee ani com.apigee. Te nazwy są zarezerwowane i używane przez inne moduły Apigee.

Sposób prezentacji

Umieść plik JAR w proxy interfejsu API w katalogu /resources/java. Jeśli wywołanie Java korzysta z dodatkowych bibliotek innych firm spakowanych jako niezależne pliki JAR, umieść te pliki JAR również w katalogu /resources/java, aby mieć pewność, że zostaną prawidłowo wczytane w czasie działania.

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

Informacje o przesyłaniu plików JAR Java znajdziesz w sekcji Pliki zasobów.

Szczegółowy przykład pokazujący, jak spakować i wdrożyć wywołanie Java za pomocą Maven lub javac, znajdziesz w artykule Tworzenie wywołania Java.

Javadoc

Dokumentacja Javadoc dotycząca pisania kodu wywołania Java jest dostępna tutaj na GitHubie. Musisz sklonować lub pobrać kod HTML na swój komputer, a następnie otworzyć plik index.html w przeglądarce.

Uwagi dotyczące użytkowania

  • Zasady wywołania Java nie zawierają rzeczywistego kodu. Zamiast tego odwołują się do „zasobu” Java i określają krok w przepływie interfejsu API, w którym jest wykonywany kod Java. Plik JAR Java możesz przesłać za pomocą edytora proxy w interfejsie zarządzania lub dołączyć go do /resources/java katalogu w proxy interfejsu API, które tworzysz lokalnie.
  • W przypadku prostych operacji, takich jak wywołania API do usług zdalnych, zalecamy używanie zasad wywołania usługi wywołania usługi. Zobacz Zasady wywołania usługi.
  • W przypadku stosunkowo prostych interakcji z treścią wiadomości, takich jak modyfikowanie lub wyodrębnianie nagłówków HTTP, parametrów lub treści wiadomości, Apigee zaleca używanie zasad JavaScript.

Powiązane artykuły